@reventlessdev/rescript-pulumi-aws 3.0.0-alpha.2 → 3.0.0-alpha.21

package/src/AppSync/AppSync_Resolver_Functions.res

@@ -4,12 +4,11 @@
     exported `request` and `response` functions, ready to be passed as the `code`
     field of AppSync_Resolver.makeUnitJsResolver / makePipelineJsResolver.
 */
-
-// ---------------------------------------------------------------------------
+let // ---------------------------------------------------------------------------
 // Shared response snippets (inlined into each resolver's template literal)
 // ---------------------------------------------------------------------------
 
-let resultResponseCode = `
+resultResponseCode = `
 export function response(ctx) {
   if (ctx.error) util.error(ctx.error.message, ctx.error.type);
   return ctx.result;
@@ -30,19 +29,11 @@ export function response(ctx) {
 let importUtil = `import { util } from '@aws-appsync/utils';`
 
 /**
-The caller-is-exempt test, emitted into a resolver's response.
-
-Mirrors `Reventless.OwnerScope.resolve` — the same branch order for the same
-reason the list predicate gives: an IAM-signed service caller has no `sub`
-because it is inside the trust boundary, not because it is anonymous, so the
-provider question is answered before the identity one.
-
-In the RESPONSE rather than the request, because a `GetItem` has no
-FilterExpression to carry a predicate: the row is fetched by key and the
-decision is made on what came back. A `Query` could filter server-side, and
-deliberately does not — a single-row read that filtered in one place and
-guarded in another would have two implementations of one rule, and the cheaper
-one is the one nobody would remember to change.
+The caller-is-exempt test, emitted into a resolver's response. Mirrors
+`Reventless.OwnerScope.resolve`, branch order included — an IAM-signed caller has
+no `sub` because it is inside the trust boundary, not because it is anonymous.
+In the response because `GetItem` has no FilterExpression; `Query` follows it so
+one rule keeps one implementation.
 */
 let ownerGuardPreamble = (~ownerField: string, ~elevatedGroups: array<string>) => {
   let elevatedLiteral = elevatedGroups->Array.map(g => `'${g}'`)->Array.join(", ")
@@ -56,12 +47,9 @@ let ownerGuardPreamble = (~ownerField: string, ~elevatedGroups: array<string>) =
 }
 
 /**
-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.
+The exemption test alone, for a door that narrows retirement but declares no
+`@owner`. Emitted only when `ownerGuardPreamble` is absent — two `const _exempt`
+in one body is a syntax error, and two different ones would be worse.
 */
 let exemptPreamble = (~elevatedGroups: array<string>) => {
   let elevatedLiteral = elevatedGroups->Array.map(g => `'${g}'`)->Array.join(", ")
@@ -75,22 +63,14 @@ let exemptPreamble = (~elevatedGroups: array<string>) => {
 
 /**
 A by-key read's retirement guard: `_live(row)`, true when the caller may see it.
+The post-read half of what `listAllItemsConnection` pushes into a
+FilterExpression — `GetItem` has none to push into.
 
-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.
+`row[field] == null` keeps a row written before the annotation existed. Exemption
+alone withholds a retired row until `includeRetired` is passed, so an operator's
+ordinary read is as narrow as anyone's.
 
-`~ownerScoped` says whether an `ownerGuardPreamble` has already been emitted into
-the same body; when it has, this reuses its `_exempt` instead of redeclaring one.
+`~ownerScoped` says an `ownerGuardPreamble` already declared `_exempt` here.
 */
 let retiredGuardPreamble = (
   ~retiredField: option<string>,
@@ -116,23 +96,15 @@ let retiredGuardPreamble = (
   }
 
 /**
-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.
+The `@owner` predicate for an index door, as a FilterExpression clause. Same rule
+and branch order as `listAllItemsConnection`'s, and pushed into the read for the
+same reason.
+
+**Not applied to a group-restricted index.** There `authorizeIndexedAccess`
+already gates the caller, and the 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 revoke exactly what the auth table granted.
+`QueryDbResolvers_AppSync` passes `ownerField` only for doors with no such rule.
 */
 let ownerFilterClause = (~ownerField: option<string>, ~elevatedGroups: array<string>) =>
   switch ownerField {
@@ -158,16 +130,12 @@ let ownerFilterClause = (~ownerField: option<string>, ~elevatedGroups: array<str
 
 /**
 The same retirement predicate as `retiredGuardPreamble`, for a door that reads
-with `Query` and therefore has a FilterExpression to put it in.
+with `Query` and so has a FilterExpression to put it in. Pushed into the read
+rather than applied after it, or the page comes back short with nothing said
+about why.
 
-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.
+Appends to the `expression` / `names` / `values` the index templates already
+build, so it composes with a caller's own filter arguments.
 */
 let retiredFilterClause = (
   ~retiredField: option<string>,
@@ -207,13 +175,9 @@ ${assignments}
 /**
 A by-key read's response, refusing a row the caller does not own.
 
-**Null, not an error** — which is the opposite of what a first reading suggests,
-since "you may not read this" and "there is nothing here" are different answers
-and only one of them is true. Two things settle it. The in-process platform
-already answers `null` here, and a rule enforced differently per transport is
-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.
+**Null, not an error.** The in-process platform answers `null` here, and a rule
+enforced differently per transport is what owner scoping exists to avoid. An
+error would also confirm the row exists to a caller who may not read it.
 */
 let ownerScopedResultResponse = (
   ~ownerField: option<string>,
@@ -226,15 +190,18 @@ let ownerScopedResultResponse = (
   | _ =>
     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;"
+    // 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)}`
+  // ── owner scoping (generated) ──${ownerGuardPreamble(
+          ~ownerField=field,
+          ~elevatedGroups,
+        )}`
     }
     let retiredPart = retiredGuardPreamble(
       ~retiredField,
@@ -245,7 +212,9 @@ let ownerScopedResultResponse = (
     `
 export function response(ctx) {
   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;
+  return _owns(ctx.result)${retiredField->Option.isSome
+        ? " && _live(ctx.result)"
+        : ""} ? ctx.result : null;
 }`
   }
 
@@ -261,15 +230,18 @@ let ownerScopedFirstResultResponse = (
   | _ =>
     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;"
+    // 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)}`
+  // ── owner scoping (generated) ──${ownerGuardPreamble(
+          ~ownerField=field,
+          ~elevatedGroups,
+        )}`
     }
     let retiredPart = retiredGuardPreamble(
       ~retiredField,
@@ -290,8 +262,7 @@ export function response(ctx) {
 // ---------------------------------------------------------------------------
 
 /** Pipeline resolver code with no pre-processing and a standard error-check response. */
-let pipelinePassThrough =
-  `${importUtil}
+let pipelinePassThrough = `${importUtil}
 export function request(ctx) { return {}; }
 ${resultResponseCode}
 `->Pulumi.Input.make
@@ -303,12 +274,9 @@ ${resultResponseCode}
 /** 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. */
+    (`@aws-appsync/no-try`), and nothing is lost — `util.base64Decode` returns
+    bytes rather than throwing on malformed input, so an unparseable id stashes
+    both halves as null, which is what a guarded version reported anyway. */
 let nodeDecodeGlobalId =
   `${importUtil}
 export function request(ctx) {
@@ -367,8 +335,7 @@ export function request(ctx) {
 ${ownerScopedResultResponse(~ownerField, ~elevatedGroups, ~retiredField?, ~retiredValues?)}
 `->Pulumi.Input.make
 
-let queryById =
-  `${importUtil}
+let queryById = `${importUtil}
 export function request(ctx) {
   return {
     operation: 'Query',
@@ -386,11 +353,11 @@ ${resultResponseCode}
     Relay pagination: `first`/`after` (forward) or `last`/`before` (backward).
     Cursor is base64 of the sort key value.
     Returns a Relay `{ edges, pageInfo }` shape reusing the entity's `Connection` type. */
-// A list in everything but its name, so it scopes the way `listAllItemsConnection`
+let // A list in everything but its name, so it scopes the way `listAllItemsConnection`
 // does — a FilterExpression on the request, not a guard on the response. The
 // response is where the page is cut, and narrowing after that cut would report
 // `hasNextPage` from a count the caller was never allowed to see.
-let queryItemsWithSortConditions = (
+queryItemsWithSortConditions = (
   sortField: string,
   ~ownerField: option<string>=?,
   ~elevatedGroups: array<string>=[],
@@ -585,61 +552,191 @@ export function request(ctx) {
 ${resultResponseCode}
 `->Pulumi.Input.make
 
+// ---------------------------------------------------------------------------
+// Paging a filtered read
+// ---------------------------------------------------------------------------
+
 /**
-The by-index door's response.
+Rows a read may EXAMINE per page.
 
-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.
+`Limit` applies before the FilterExpression, so reading `first` rows and returning
+the survivors serves short — usually empty — pages under a selective filter. With
+no loops in APPSYNC_JS the door reads wider instead and addresses the surplus by
+position. 1 MB caps a page anyway, hence 1000; `filtered` is the JS expression
+saying whether a filter was pushed down.
+*/
+let pageWindowBudget = (~filtered: string) =>
+  `(${filtered} ? (_first > 1000 ? _first : 1000) : _first + _from)`
 
-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.
+/**
+The same budget for the full-list door, which may also read backward.
+
+A backward page is the slice `[_from, _upTo)` of the window, so the read has to
+reach `_upTo` rows into it — `_first + _from` would stop short and hand back a
+page with its tail missing.
 */
-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) => ({
+let listPageWindowBudget = {
+  let need = "(_backward ? _upTo : _first + _from)"
+  `(parts.length > 0 ? (${need} > 1000 ? ${need} : 1000) : ${need})`
+}
+
+/**
+Decodes `after` into the window it names (`t`, the token opening it) and the row's
+index among that window's matches (`n`). Pre-window cursors carried
+`{token, index}` naming the window that follows — position -1 of it.
+
+`p` is the one-character tag naming which read the window belongs to (`s` Scan,
+`q` the owner-index Query). Absent reads as `s`: every cursor minted before the
+tag existed came off a Scan. Only a door with more than one read tests it — see
+`cursorPathGuard`.
+*/
+let cursorDecode = (~args: string) =>
+  `
+  let _window = null;
+  let _from = 0;
+  let _cursorPath = null;
+  if (${args}.after != null && ${args}.after !== '') {
+    const _c = JSON.parse(util.base64Decode(${args}.after));
+    _window = (_c.t !== undefined ? _c.t : _c.token) ?? null;
+    _from = _c.n !== undefined ? _c.n + 1 : 0;
+    _cursorPath = _c.p ?? 's';
+  }`
+
+/**
+Refuses a cursor minted on this door's other read. The two branches are selectable
+by the SAME caller across requests — an active-role switch mid-pagination flips
+`_exempt` — and a `nextToken` continues the operation that issued it, so replaying
+one on the other branch answers a different question without saying so.
+
+Expects `_cursorPath` from `cursorDecode` and `_exempt` from the owner preamble.
+*/
+let cursorPathGuard = `
+  if (_cursorPath !== null && _cursorPath !== (_exempt ? 's' : 'q')) {
+    util.error('This cursor belongs to a different read of this list; restart from the first page.', 'CursorPathMismatch');
+  }`
+
+/**
+The full-list door's cursor decode, which unlike `cursorDecode` may run backward.
+
+A `{t, n}` cursor names a position INSIDE a read window, and a window is re-read
+from its own token — which forward paging already relies on to resume mid-window.
+Backward is the same move in the other direction: re-read the window `before`
+names and cut the page that ends at `n`, `[n - first, n)`. No new cursor shape, no
+index, and no assumption forward paging does not already make.
+
+What it cannot do is cross into an EARLIER window: DynamoDB's continuation chain
+walks one way, so a window cannot name the one before it. `_upTo <= 0` with a
+non-null window is that case, and it is the only one still refused.
+
+Declares `_first` (the response's slicing needs it before `connectionPageResponse`
+would have declared it, so that one omits it here).
+*/
+let listCursorPreamble = `
+  const _first = ctx.args.first ?? 50;
+  let _window = null;
+  let _from = 0;
+  let _cursorPath = null;
+  let _backward = false;
+  let _upTo = -1;
+  if (ctx.args.before != null && ctx.args.before !== '') {
+    const _c = JSON.parse(util.base64Decode(ctx.args.before));
+    _window = (_c.t !== undefined ? _c.t : _c.token) ?? null;
+    _cursorPath = _c.p ?? 's';
+    _backward = true;
+    _upTo = _c.n !== undefined ? _c.n : 0;
+    _from = (_upTo - _first) > 0 ? (_upTo - _first) : 0;
+  } else if (ctx.args.after != null && ctx.args.after !== '') {
+    const _c = JSON.parse(util.base64Decode(ctx.args.after));
+    _window = (_c.t !== undefined ? _c.t : _c.token) ?? null;
+    _from = _c.n !== undefined ? _c.n + 1 : 0;
+    _cursorPath = _c.p ?? 's';
+  }`
+
+/**
+Cuts the requested page out of the returned window. Expects `items` (sorted, if the
+door sorts) plus `_window` / `_from` from `cursorDecode`. `pathExpr` is the JS
+expression naming which read minted these cursors, for a door that has two.
+
+`bidirectional` is the full-list door, whose page may have been cut backward: it
+reads `_backward` / `_upTo` from `listCursorPreamble` and takes `_first` from
+there rather than declaring its own.
+*/
+let connectionPageResponse = (~pathExpr: option<string>=?, ~bidirectional: bool=false) => {
+  let tag = switch pathExpr {
+  | None => ""
+  | Some(e) => `, p: ${e}`
+  }
+  let firstDecl = bidirectional ? "" : "\n  const _first = ctx.args.first ?? 50;"
+  let slice = bidirectional
+    ? `
+  const _rest = _backward ? items.slice(_from, _upTo) : items.slice(_from);
+  const _page = _backward ? _rest : _rest.slice(0, _first);
+  // A backward page was cut from ahead, so a next page provably exists — the one
+  // the caller came from — whatever this window's tail looks like.
+  const _more = _backward ? true : _rest.length > _first;`
+    : `
+  const _rest = items.slice(_from);
+  const _page = _rest.slice(0, _first);
+  const _more = _rest.length > _first;`
+  // Only what the door can actually serve. `!!ctx.args.after` said "a page
+  // precedes this one", which is a different claim: at a window boundary one does
+  // and this door cannot reach it, so the client drew a Prev that always errored.
+  let hasPrevious = bidirectional ? "_from > 0" : "!!ctx.args.after"
+  `${firstDecl}${slice}
+  const _next = ctx.result?.nextToken ?? null;
+  const _lastIndex = _page.length - 1;
+  // A row's cursor names its own position. The last row of a page that closes its
+  // window is the exception — no position follows it there, so it names the next
+  // window, or resuming from it answers blank.
+  const edges = _page.map((item, i) => ({
     node: item,
-    cursor: util.base64Encode(JSON.stringify({ token: next, index: i })),
+    cursor: util.base64Encode(JSON.stringify(
+      (!_more && _next && i === _lastIndex)
+        ? { t: _next, n: -1${tag} }
+        : { t: _window, n: _from + i${tag} }
+    )),
   }));
-  const boundary = next ? util.base64Encode(JSON.stringify({ token: next, index: -1 })) : null;
+  // A window the filter emptied leaves no row to cut a cursor from; the token is
+  // the window's, so a client can step past it rather than restart.
+  const _boundary = _next ? util.base64Encode(JSON.stringify({ t: _next, n: -1${tag} })) : 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,
+      hasNextPage: _more || !!_next,
+      hasPreviousPage: ${hasPrevious},
+      startCursor: edges.length > 0 ? edges[0].cursor : _boundary,
+      endCursor: edges.length > 0 ? edges[edges.length - 1].cursor : _boundary,
     },
-  };
+  };`
+}
+
+/**
+The by-index door's response. Pages out of a read window exactly as
+`listAllItemsConnection` does, and satisfies the `Connection!` the field has always
+declared — returning `ctx.result` raw did not.
+*/
+let indexConnectionResponseCode = `
+export function response(ctx) {
+  if (ctx.error) util.error(ctx.error.message, ctx.error.type);
+  const items = ctx.result?.items ?? [];${cursorDecode(~args="ctx.args")}${connectionPageResponse()}
 }`
 
 /** 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. */
+`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. */
 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;
-  }`
+/** Decodes the Relay `after` cursor back to the read window the response side
+encoded, and sizes the window this read may examine. Mirrors
+`listAllItemsConnection`'s request half. */
+let indexCursorPreamble = `${cursorDecode(~args="args")}
+  const _first = args.first ?? 50;`
 
 // 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
@@ -688,13 +785,17 @@ export function request(ctx) {
       values[':' + key] = '' + value;
     }
   });
-${ownerFilterClause(~ownerField, ~elevatedGroups)}${retiredFilterClause(~retiredField, ~retiredValues, ~elevatedGroups)}${indexCursorPreamble}
+${ownerFilterClause(~ownerField, ~elevatedGroups)}${retiredFilterClause(
+      ~retiredField,
+      ~retiredValues,
+      ~elevatedGroups,
+    )}${indexCursorPreamble}
   const result = {
     operation: 'Query',
     query,
     index: '${index}',
-    limit: (args.first ?? 50),
-    nextToken: after,
+    limit: ${pageWindowBudget(~filtered="expression")},
+    nextToken: _window,
     scanIndexForward: (args.forward ?? true)
   };
   if (expression) {
@@ -751,13 +852,17 @@ export function request(ctx) {
       values[':' + key] = '' + value;
     }
   });
-${ownerFilterClause(~ownerField, ~elevatedGroups)}${retiredFilterClause(~retiredField, ~retiredValues, ~elevatedGroups)}${indexCursorPreamble}
+${ownerFilterClause(~ownerField, ~elevatedGroups)}${retiredFilterClause(
+      ~retiredField,
+      ~retiredValues,
+      ~elevatedGroups,
+    )}${indexCursorPreamble}
   const result = {
     operation: 'Query',
     query,
     index: '${index}',
-    limit: (args.first ?? 50),
-    nextToken: after,
+    limit: ${pageWindowBudget(~filtered="expression")},
+    nextToken: _window,
     scanIndexForward: (args.forward ?? true)
   };
   if (expression) {
@@ -772,8 +877,7 @@ ${indexConnectionResponseCode}
 // DynamoDB read — list all
 // ---------------------------------------------------------------------------
 
-let listAllItems =
-  `${importUtil}
+let listAllItems = `${importUtil}
 export function request(ctx) {
   return {
     operation: 'Scan',
@@ -789,48 +893,36 @@ ${resultResponseCode}
 // ---------------------------------------------------------------------------
 
 /**
- * Scan with optional `filter` arg: `{search?, searchPrefix?, ids?, <field>Eq?, <field>From?, <field>To?}`
- * and optional `orderBy: {field, direction}`.
- *
- * `search`       → `contains(labelField, :v)` — case-sensitive on DynamoDB. Callers that
- *                  need case-insensitive matching should project a lowercased label column
- *                  (future Phase 6.1 / external full-text search).
- * `searchPrefix` → `begins_with(labelField, :v)` — case-sensitive. Scan-only here;
- *                  Phase 6 `@searchable` provisions a GSI to promote this to a query.
- * `ids`          → FilterExpression `#id IN (:id0, :id1, …)`. Simple scan-based
- *                  path; BatchGetItem optimisation is deferred (open question 1).
- * `<field>Eq`    → FilterExpression `#<field> = :<field>Eq`, one per `~filterFields` entry.
- * `<field>From`  → FilterExpression `#<field> >= :<field>From`, one per `~rangeFields` entry.
- * `<field>To`    → FilterExpression `#<field> <= :<field>To`, one per `~rangeFields` entry.
- * `orderBy`      → JS-runtime sort over the returned page when `orderBy.field` is in
- *                  `~sortFields`. **Per-page only**, not global — DynamoDB Scan returns
- *                  items in indeterminate order and `ScanIndexForward` does not apply
- *                  to Scan. Index-routed Query (v1.5) lifts this caveat for indexed
- *                  sort fields; `@scanSort` on a non-indexed field is per-page even then.
- *
- * Empty-string and null filter values are treated as "no filter" — consistent with the
- * in-memory adapter so clients don't need to conditionally omit keys.
- */
+Scan behind `filter: {search?, searchPrefix?, ids?, <field>Eq?, <field>From?,
+<field>To?}` and `orderBy: {field, direction}`. `search` / `searchPrefix` become
+`contains` / `begins_with` on `labelField` (case-sensitive — a case-insensitive
+match wants a lowercased projected column); `ids` becomes `#id IN (…)`; the
+per-field forms become `=` / `>=` / `<=`.
+
+`orderBy` sorts in the JS runtime over the read window, not globally: Scan returns
+items in indeterminate order and `ScanIndexForward` is Query-only. Empty and null
+filter values mean "no filter", as they do in-memory.
+
+With `ownerIndex` the door has **two** reads against the same data source, chosen
+by whether the caller is exempt from owner scoping: a Query on the derived
+`@owner` index for a scoped caller, the Scan above for everyone else. A user
+`filter` still lands in a FilterExpression on top of the Query's key condition, so
+a scoped caller searching their own rows can still get a short page — but bounded
+by their row count rather than the table's.
+*/
 let listAllItemsConnection = (
   ~labelField: string,
   ~filterFields: array<string>=[],
   ~rangeFields: array<string>=[],
   ~sortFields: array<string>=[],
-  // When set, emit an always-on `attribute_exists(#<attr>)` FilterExpression clause
-  // (ANDed with any client filters) so rows lacking that attribute never enter the
-  // Connection. Used for read models whose physical DynamoDB table co-hosts internal
-  // bookkeeping rows written outside the projection (e.g. the Plugins admin RM, whose
-  // table also holds `deploy-schema:*` / `plugin-info:*` rows with no `name`). Those
-  // rows would otherwise resolve `name`/`status`/`version` to null and violate the
-  // non-null GraphQL connection schema, nulling the whole connection.
+  // An always-on `attribute_exists(#<attr>)` clause, for a read model whose table
+  // co-hosts bookkeeping rows written outside the projection (the Plugins admin RM's
+  // `deploy-schema:*` / `plugin-info:*` rows carry no `name`). Those rows resolve
+  // non-null fields to null and take the whole Connection with them.
   ~requireAttribute: option<string>=?,
-  // The state's `@owner` field, when it declares one, plus the groups exempt from
-  // scoping. Baked into the generated source because this resolver runs inside
-  // AppSync with no Lambda in the path — there is nothing here that could read a
-  // configuration value at request time, so the deploy is the only chance to
-  // state it. Changing the elevated-group list therefore requires a redeploy,
-  // which is worth knowing and is why it is a deployment-level setting rather
-  // than a per-request one.
+  // The state's `@owner` field and the groups exempt from scoping. Baked in
+  // because no Lambda sits in this path to read a value at request time, so the
+  // elevated-group list changes only on redeploy.
   ~ownerField: option<string>=?,
   ~elevatedGroups: array<string>=[],
   // The state's `@retired` field, when it declares one. Baked in for the same
@@ -840,9 +932,17 @@ let listAllItemsConnection = (
   // The states that retire the row, for the state form of the annotation.
   // Absent is the boolean form, where the value is always `true`.
   ~retiredValues: option<array<string>>=?,
+  // The index `@owner` derives, and its sort key. Present turns the owner
+  // predicate from a post-read sieve into a key condition for a scoped caller.
+  ~ownerIndex: option<string>=?,
+  ~ownerIndexSortField: option<string>=?,
 ) => {
+  // The Query branch needs `ownerField` to key on; an index without one would
+  // have nothing to name in the key condition.
+  let ownerIndex = ownerField->Option.isSome ? ownerIndex : None
   let requireAttributeClause = switch requireAttribute {
-  | Some(attr) => `
+  | Some(attr) =>
+    `
   names['#${attr}'] = '${attr}';
   parts.push('attribute_exists(#${attr})');`
   | None => ""
@@ -851,9 +951,11 @@ let listAllItemsConnection = (
   // it. The branch ORDER is the part that has to match: provider first, because
   // an IAM-signed service caller has no `sub` for a reason that has nothing to do
   // with being anonymous, and must not be refused as though it did.
-  let ownerClause = switch ownerField {
-  | None => ""
-  | Some(field) =>
+  //
+  // Emitted in BOTH halves of the resolver when an owner index is in play: the
+  // response has to know which read minted the cursors it hands out, and that is
+  // the same question.
+  let ownerIdentityPreamble = {
     let elevatedLiteral = elevatedGroups->Array.map(g => `'${g}'`)->Array.join(", ")
     `
   // ── owner scoping (generated) ──
@@ -866,7 +968,16 @@ let listAllItemsConnection = (
   const _elevated = [${elevatedLiteral}];
   // No identity at all, or an identity with no \`sub\`, is the IAM service caller
   // the API also accepts — inside the trust boundary, and exempt.
-  const _exempt = _sub == null || _groups.some(g => _elevated.indexOf(g) >= 0);
+  const _exempt = _sub == null || _groups.some(g => _elevated.indexOf(g) >= 0);`
+  }
+  let ownerClause = switch (ownerField, ownerIndex) {
+  | (None, _) => ""
+  // With an index the predicate is the Query's key condition, so nothing is
+  // pushed into the filter — and nothing may be: an expressionName the filter
+  // never references is a ValidationException, not a harmless extra.
+  | (Some(_), Some(_)) => ownerIdentityPreamble
+  | (Some(field), None) =>
+    `${ownerIdentityPreamble}
   if (!_exempt) {
     names['#owner'] = '${field}';
     values[':owner'] = util.dynamodb.toDynamoDB(_sub);
@@ -874,32 +985,23 @@ let listAllItemsConnection = (
   }`
   }
   // ── retirement narrowing (generated) ──
-  // Reuses `_exempt` when the owner clause already computed it, and computes its
-  // own when it did not — the two clauses are independently optional and either
-  // may be the only one present.
-  //
-  // `includeRetired` IS read from ctx.args, unlike the owner predicate, and the
-  // difference is deliberate: this argument does not say which rows the caller
-  // wants, it asks to lift a restriction, and it is honoured only inside the
-  // `_exempt` branch. A non-exempt caller passing it changes nothing.
+  // Reuses `_exempt` when the owner clause computed it; either clause may be the
+  // only one present. `includeRetired` IS read from ctx.args, unlike the owner
+  // predicate — it asks to lift a restriction rather than naming rows, and is
+  // honoured only inside `_exempt`.
   //
-  // `attribute_not_exists OR = false` rather than `<> true`: a row written before
-  // the annotation existed carries no such attribute, and DynamoDB's `<>` does
-  // not match a missing one — the whole view would come back empty on the day
-  // the annotation lands.
-  //
-  // The state form compares `<>` against the retiring state instead, under the
-  // same `attribute_not_exists` guard and for the same reason. An equality
-  // predicate over an enum-valued attribute indexes exactly as a boolean one
-  // does, so the warning about an unindexed retirement field carries over
-  // unchanged.
+  // `attribute_not_exists OR = false` rather than `<> true`, because `<>` does not
+  // match a missing attribute and the view would empty out the day the annotation
+  // lands. The state form compares `<>` against the retiring state under the same
+  // guard.
   let retiredClause = switch retiredField {
   | None => ""
   | Some(field) =>
     let elevatedLiteral = elevatedGroups->Array.map(g => `'${g}'`)->Array.join(", ")
     let exemptPrelude = switch ownerField {
     | Some(_) => ""
-    | None => `
+    | None =>
+      `
   const _id = ctx.identity;
   const _sub = _id == null ? null : _id.sub;
   const _groups = (_id != null && _id.claims != null && _id.claims['cognito:groups']) || [];
@@ -920,10 +1022,13 @@ ${switch retiredValues {
       // once for the whole clause — a row that states no lifecycle is not
       // retired, the same reading every other adapter takes.
       | Some(states) =>
-        let placeholders = states->Array.mapWithIndex((state, i) => (`:retiredValue${Int.toString(i)}`, state))
+        let placeholders =
+          states->Array.mapWithIndex((state, i) => (`:retiredValue${Int.toString(i)}`, state))
         let assignments =
           placeholders
-          ->Array.map(((ph, state)) => `    values['${ph}'] = util.dynamodb.toDynamoDB('${state}');`)
+          ->Array.map(((ph, state)) =>
+            `    values['${ph}'] = util.dynamodb.toDynamoDB('${state}');`
+          )
           ->Array.join("\n")
         let comparisons =
           placeholders->Array.map(((ph, _)) => `#retired <> ${ph}`)->Array.join(" AND ")
@@ -939,16 +1044,19 @@ ${switch retiredValues {
   }
   let filterClauses =
     filterFields
-    ->Array.map(f => `
+    ->Array.map(f =>
+      `
   if (filter.${f}Eq !== undefined && filter.${f}Eq !== null && filter.${f}Eq !== '') {
     names['#${f}'] = '${f}';
     values[':${f}Eq'] = util.dynamodb.toDynamoDB(filter.${f}Eq);
     parts.push('#${f} = :${f}Eq');
-  }`)
+  }`
+    )
     ->Array.join("")
   let rangeClauses =
     rangeFields
-    ->Array.map(f => `
+    ->Array.map(f =>
+      `
   if (filter.${f}From !== undefined && filter.${f}From !== null && filter.${f}From !== '') {
     names['#${f}'] = '${f}';
     values[':${f}From'] = util.dynamodb.toDynamoDB(filter.${f}From);
@@ -958,29 +1066,32 @@ ${switch retiredValues {
     names['#${f}'] = '${f}';
     values[':${f}To'] = util.dynamodb.toDynamoDB(filter.${f}To);
     parts.push('#${f} <= :${f}To');
-  }`)
+  }`
+    )
     ->Array.join("")
-  let sortFieldsLiteral =
-    sortFields->Array.map(f => `'${f}'`)->Array.join(", ")
+  let sortFieldsLiteral = sortFields->Array.map(f => `'${f}'`)->Array.join(", ")
+  // When the Query branch already ordered on the index's own sort key, the page
+  // arrives globally ordered and re-sorting it here is the one way to break that
+  // order — a sort over a page is not a sort over the caller's rows.
+  let sortGuard = switch (ownerIndex, ownerIndexSortField) {
+  | (Some(_), Some(_)) => "!_indexOrdered && "
+  | _ => ""
+  }
   let sortBlock = if sortFields->Array.length == 0 {
     ""
   } else {
-    // APPSYNC_JS 1.0.0 forbids: Array.prototype.sort(comparator), arrow/function
-    // expressions passed to sort, for/while loops, recursion, and ++/--. So we
-    // can't run a comparator-driven sort and we can't write our own loop. Use a
-    // schwartzian transform: encode each item as `<sortKey>\x01<json>`, run the
-    // no-comparator default sort (lexicographic), reverse for DESC, and decode.
-    // Numeric fields get zero-padded so lex order matches numeric order for
-    // non-negative values (typical for IDs, counts, timestamps). Negatives sort
-    // lexicographically — acceptable since DynamoDB sort keys are rarely signed
-    // numbers. Nulls split out and append to the end regardless of direction.
+    // APPSYNC_JS 1.0.0 forbids comparator sorts, loops, recursion and ++/--, so
+    // this is a schwartzian transform: encode each item as `<sortKey>\x01<json>`,
+    // default-sort lexicographically, reverse for DESC, decode. Numbers are
+    // zero-padded so lex order matches numeric order for non-negative values;
+    // nulls split out and append to the end either way.
     `
   // Per-page sort (Scan returns items in indeterminate order; ScanIndexForward
   // does not apply to Scan). Global ordering across pages requires v1.5 index
   // promotion; @scanSort is per-page even then.
   const orderBy = ctx.args.orderBy;
   const sortFields = [${sortFieldsLiteral}];
-  if (orderBy && orderBy.field && sortFields.indexOf(orderBy.field) >= 0) {
+  if (${sortGuard}orderBy && orderBy.field && sortFields.indexOf(orderBy.field) >= 0) {
     const field = orderBy.field;
     const nulls = items.filter(it => it[field] === null || it[field] === undefined);
     const nonNulls = items.filter(it => it[field] !== null && it[field] !== undefined);
@@ -996,13 +1107,69 @@ ${switch retiredValues {
     items = encoded.map(e => JSON.parse(e.split('\\x01')[1])).concat(nulls);
   }`
   }
+  // Did the Query branch order this page itself? Answered the same way in both
+  // halves, because both need it: the request to set `scanIndexForward`, the
+  // response to leave an already-ordered page alone.
+  let indexOrderedExpr = switch (ownerIndex, ownerIndexSortField) {
+  | (Some(_), Some(sf)) => `!_exempt && !!(ctx.args.orderBy && ctx.args.orderBy.field === '${sf}')`
+  | _ => "false"
+  }
+  // The two reads, chosen by the same test that used to choose a predicate.
+  // Both target the one data source the resolver is attached to, so this is a
+  // branch inside one resolver — no second field, no second data source, no
+  // client change.
+  let requestOperation = switch (ownerField, ownerIndex) {
+  | (Some(field), Some(index)) =>
+    `
+  const _indexOrdered = ${indexOrderedExpr};
+  const req = _exempt
+    ? {
+        operation: 'Scan',
+        limit: ${listPageWindowBudget},
+        nextToken: _window,
+      }
+    : {
+        operation: 'Query',
+        index: '${index}',
+        query: {
+          expression: '#owner = :owner',
+          expressionNames: { '#owner': '${field}' },
+          expressionValues: { ':owner': util.dynamodb.toDynamoDB(_sub) },
+        },
+        limit: ${listPageWindowBudget},
+        nextToken: _window,
+        scanIndexForward: !(_indexOrdered && ctx.args.orderBy.direction === 'DESC'),
+      };`
+  | _ =>
+    `
+  const req = {
+    operation: 'Scan',
+    limit: ${listPageWindowBudget},
+    nextToken: _window,
+  };`
+  }
+  // Only a door with two reads tests the tag, and only that door stamps one.
+  let requestPathGuard = ownerIndex->Option.isSome ? cursorPathGuard : ""
+  let responsePathPreamble = switch ownerIndex {
+  | None => ""
+  | Some(_) =>
+    `${ownerIdentityPreamble}
+  const _path = _exempt ? 's' : 'q';
+  const _indexOrdered = ${indexOrderedExpr};`
+  }
+  let pageResponse = switch ownerIndex {
+  | None => connectionPageResponse(~bidirectional=true)
+  | Some(_) => connectionPageResponse(~pathExpr="_path", ~bidirectional=true)
+  }
   `${importUtil}
 export function request(ctx) {
-  // Scan cannot page backward (ScanIndexForward is Query-only). Fail loud rather than
-  // silently returning the forward page. The ordered {single}Items connection
-  // (queryItemsWithSortConditions) supports last/before — direct backward callers there.
-  if (ctx.args.before != null || ctx.args.last != null) {
-    util.error('Backward pagination (last/before) is not supported on full-list connections; use first/after.', 'UnsupportedPagination');
+  // 'before' IS served — the page is cut backward out of the window the cursor
+  // names. 'last' is not: "the last N rows of the list" needs the end of the
+  // list, which a forward-only Scan cursor cannot reach. The ordered
+  // {single}Items connection (queryItemsWithSortConditions) has a real keyset
+  // cursor and honours both — direct callers who need 'last' there.
+  if (ctx.args.last != null) {
+    util.error('last is not supported on full-list connections; page backward with first and before.', 'UnsupportedPagination');
   }
   const filter = ctx.args.filter ?? {};
   const names = {};
@@ -1027,18 +1194,14 @@ export function request(ctx) {
     });
     parts.push('#id IN (' + placeholders.join(', ') + ')');
   }${filterClauses}${rangeClauses}${requireAttributeClause}${ownerClause}${retiredClause}
-  // The cursor is base64(JSON({ token, index })); decode the after arg back to the raw
-  // DynamoDB continuation token the response side emitted (Fix 1 round-trip).
-  let after = null;
-  if (ctx.args.after != null && ctx.args.after !== '') {
-    const parsed = JSON.parse(util.base64Decode(ctx.args.after));
-    after = parsed.token ?? null;
-  }
-  const req = {
-    operation: 'Scan',
-    limit: (ctx.args.first ?? 50),
-    nextToken: after,
-  };
+${listCursorPreamble}${requestPathGuard}
+  // The one page a cursor cannot reach: it begins in an earlier window, and a
+  // continuation token cannot name the one before it. Refused by itself rather
+  // than folded into the 'last' guard, because the two are different limits and a
+  // caller can act on this one (page forward from the start).
+  if (_backward && _upTo <= 0 && _window !== null) {
+    util.error('The previous page begins in an earlier read window, which this cursor cannot name; page forward from the start.', 'UnsupportedPagination');
+  }${requestOperation}
   if (parts.length > 0) {
     req.filter = {
       expression: parts.join(' AND '),
@@ -1050,30 +1213,7 @@ export function request(ctx) {
 }
 export function response(ctx) {
   if (ctx.error) util.error(ctx.error.message, ctx.error.type);
-  let items = ctx.result?.items ?? [];${sortBlock}
-  // One Scan continuation token per page; encode it (with the item's page index for a
-  // unique, opaque Relay cursor). The request side decodes .token back to the raw
-  // DynamoDB nextToken (Fix 1).
-  const next = ctx.result?.nextToken ?? null;
-  const edges = items.map((item, i) => ({
-    node: item,
-    cursor: util.base64Encode(JSON.stringify({ token: next, index: i })),
-  }));
-  // A filtered/1MB-capped page can be empty or short while next is still set (limit
-  // caps rows scanned, not returned). The token is page-level, so synthesise a
-  // boundary cursor from it alone so a client can resume past a fully-filtered-out
-  // page instead of restarting from page 1 (Fix 3). The request only reads .token,
-  // so index -1 is inert on resume.
-  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 items = ctx.result?.items ?? [];${responsePathPreamble}${sortBlock}${listCursorPreamble}${pageResponse}
 }
 `->Pulumi.Input.make
 }
@@ -1085,14 +1225,10 @@ export function response(ctx) {
 /**
 The response of a cross-table field (`@resolves`) over a Query-shaped read.
 
-The narrowing is the TARGET's, not the declaring view's: the row comes out of the
-target's table, so whether this caller may see it is the target's question — asked
-here with the same `_owns` / `_live` guards every by-key door on that table asks.
-
-A nested field takes no `includeRetired` argument, so `_wantsRetired` is never
-true and a retired row never travels through one. A reference that must keep
-reading as a name after the archive took it is what `{list}Refs` + `@namedWhenRetired`
-answers.
+The narrowing is the TARGET's, not the declaring view's — the row is the target's,
+so it answers with the same `_owns` / `_live` guards its by-key doors use. A
+nested field takes no `includeRetired`, so a retired row never travels through
+one; `{list}Refs` + `@namedWhenRetired` is that door.
 */
 let resolvedFieldResponse = (
   ~multi: bool,
@@ -1111,7 +1247,10 @@ let resolvedFieldResponse = (
     | None => "\n  const _owns = (row) => true;"
     | Some(field) =>
       `
-  // ── owner scoping (generated) ──${ownerGuardPreamble(~ownerField=field, ~elevatedGroups)}`
+  // ── owner scoping (generated) ──${ownerGuardPreamble(
+          ~ownerField=field,
+          ~elevatedGroups,
+        )}`
     }
     let retiredPart = retiredGuardPreamble(
       ~retiredField,
@@ -1303,14 +1442,10 @@ ${response}
 
 /** `@resolvesMany` — the parent's id array batch-read from the target's table.
 
-    Returns a plain string: the table name is interpolated by the adapter via
-    `Pulumi.Output.apply`, because BatchGetItem's `tables` map keys on the literal
-    name.
-
-    Same shape as `batchGetItemsByIds`, and narrowed by the same guards — the
-    target's, since the rows are the target's. Missing ids come back as nulls in
-    the result array (BatchGetItem preserves index correspondence) and are
-    dropped, so the field is shorter rather than null-holed. */
+    A plain string, because BatchGetItem's `tables` map keys on the literal name,
+    which the adapter interpolates via `Pulumi.Output.apply`. Same shape and
+    guards as `batchGetItemsByIds`; missing ids come back null and are dropped, so
+    the field is shorter rather than null-holed. */
 let resolveIds = (
   ~idsField: string,
   ~sortField: option<string>,
@@ -1318,13 +1453,14 @@ let resolveIds = (
   ~retiredField: option<string>=?,
   ~retiredValues: option<array<string>>=?,
   ~elevatedGroups: array<string>=[],
-) => (tableName: string) => {
-  let keysCode = switch sortField {
-  | Some(sf) =>
-    `id => ({ id: util.dynamodb.toString(id.id), ${sf}: util.dynamodb.toString(id.${sf}) })`
-  | None => `id => ({ id: util.dynamodb.toString(id) })`
-  }
-  `${importUtil}
+) =>
+  (tableName: string) => {
+    let keysCode = switch sortField {
+    | Some(sf) =>
+      `id => ({ id: util.dynamodb.toString(id.id), ${sf}: util.dynamodb.toString(id.${sf}) })`
+    | None => `id => ({ id: util.dynamodb.toString(id) })`
+    }
+    `${importUtil}
 import { runtime } from '@aws-appsync/utils';
 export function request(ctx) {
   const idList = ctx.source.${idsField} ?? [];
@@ -1341,36 +1477,34 @@ export function request(ctx) {
 }
 export function response(ctx) {
   if (ctx.error) util.error(ctx.error.message, ctx.error.type);${switch ownerField {
-    | None => ""
-    | Some(field) => ownerGuardPreamble(~ownerField=field, ~elevatedGroups)
-    }}${retiredGuardPreamble(
-      ~retiredField,
-      ~retiredValues,
-      ~elevatedGroups,
-      ~ownerScoped=ownerField->Option.isSome,
-    )}
+      | 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)"
-      : ""});
+        ? " && _live(item)"
+        : ""});
 }
 `
-}
+  }
 
-/** Batched-by-ids — top-level Query resolver reading `ctx.args.ids: [String!]!`
-    and returning the matching items via a single BatchGetItem. Missing ids drop
-    out (BatchGetItem does not preserve cardinality); empty input short-circuits
-    to an empty result without hitting DDB. Table name is interpolated at deploy
-    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. */
+/** Batched-by-ids — reads `ctx.args.ids: [String!]!` through one BatchGetItem.
+    Missing ids drop out; empty input short-circuits without hitting DDB. The
+    table name is interpolated at deploy time, since BatchGetItem's `tables` map
+    keys on the literal. Single-key tables only. */
 let batchGetItemsByIds = (
   ~ownerField: option<string>=?,
   ~retiredField: option<string>=?,
   ~retiredValues: option<array<string>>=?,
   ~elevatedGroups: array<string>=[],
-) => (tableName: string) =>
-  `${importUtil}
+) =>
+  (tableName: string) =>
+    `${importUtil}
 import { runtime } from '@aws-appsync/utils';
 export function request(ctx) {
   const ids = ctx.args.ids ?? [];
@@ -1387,79 +1521,79 @@ export function request(ctx) {
 }
 export function response(ctx) {
   if (ctx.error) util.error(ctx.error.message, ctx.error.type);
-  // BatchGetItem returns null in the result array for keys that don't exist
-  // in the table, preserving index correspondence with the input. The SDL
-  // returns this field as \`[T!]!\` (non-null element list), so any single
-  // 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.
+  // BatchGetItem returns null for keys that don't exist, preserving index
+  // correspondence. The SDL declares \`[T!]!\`, so one missing id would null the
+  // whole field — drop them and return what was found.
   // 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,
-    )}
+      | 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)"
-      : ""});
+        ? " && _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. */
+    The same BatchGetItem as `batchGetItemsByIds`, projected to
+    `{id, label, retired, retiredState}` by the SDL type, so the response builds
+    three fields rather than deciding what to withhold. `namedWhenRetired` decides
+    a retired row: false drops it, true names it. The owner rule applies either
+    way — that is not what the annotation lifts. */
 let refsByIds = (
   ~labelField: string,
   ~retiredField: option<string>,
   ~retiredValues: option<array<string>>,
   ~namedWhenRetired: bool,
+  // The picture a reference shows this row by, already read off the state schema
+  // by `Reventless.RowImage` — this template only bakes in the expression it
+  // hands over. `None` for a view that declares none, which emits a literal
+  // `null`, exactly what the nullable field promises.
+  ~imageExpr: option<string>=?,
   ~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}
+) =>
+  (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 ?? [];
@@ -1484,19 +1618,19 @@ export function response(ctx) {
     .map(row => ({
       id: row.id,
       label: row['${labelField}'] ?? row.id,
+      image: ${imageExpr->Option.getOr("null")},
       retired: _retired(row),
       retiredState: ${stateExpr},
     }));
 }
 `
-}
+  }
 
 // ---------------------------------------------------------------------------
 // DynamoDB write
 // ---------------------------------------------------------------------------
 
-let putItem =
-  `${importUtil}
+let putItem = `${importUtil}
 export function request(ctx) {
   return {
     operation: 'PutItem',
@@ -1523,8 +1657,7 @@ export function request(ctx) {
 ${resultResponseCode}
 `->Pulumi.Input.make
 
-let deleteItem =
-  `${importUtil}
+let deleteItem = `${importUtil}
 export function request(ctx) {
   return {
     operation: 'DeleteItem',
@@ -1667,8 +1800,7 @@ export function response(ctx) {
 let authorizeIndexedAccessRequest = authorizeIndexedAccess
 
 /** @deprecated The response check is now part of authorizeIndexedAccess. */
-let authorizeIndexedAccessResponse = (~group as _: string) =>
-  resultResponseCode->Pulumi.Input.make
+let authorizeIndexedAccessResponse = (~group as _: string) => resultResponseCode->Pulumi.Input.make
 
 // ---------------------------------------------------------------------------
 // Response-only helpers