@reventlessdev/rescript-pulumi-aws 2.4.0-alpha.77 → 2.4.0-alpha.79

package/CHANGELOG.md

@@ -3,6 +3,25 @@
 All notable changes to this project will be documented in this file.
 See [Conventional Commits](https://conventionalcommits.org) for commit guidelines.
 
+# 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
+
+* **aws:** scope by-key reads to the owner, not only lists ([8232fd4](https://github.com/ReventlessDev/reventless-core/commit/8232fd4c09c1098c7265e4a17882ee44884f3bec))
+
+
 # 2.4.0-alpha.77 (2026-08-16)
 
 ### Features

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@reventlessdev/rescript-pulumi-aws",
-  "version": "2.4.0-alpha.77",
+  "version": "2.4.0-alpha.79",
   "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-pulumi-pulumi": "2.3.0-alpha.19",
-    "@reventlessdev/rescript-aws-sdk": "3.0.0-alpha.11"
+    "@reventlessdev/rescript-aws-sdk": "3.0.0-alpha.12",
+    "@reventlessdev/rescript-pulumi-pulumi": "2.3.0-alpha.19"
   },
   "devDependencies": {
     "esbuild": "^0.25.12",

package/src/AppSync/AppSync_Resolver_Functions.res

@@ -29,6 +29,250 @@ 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.
+*/
+let ownerGuardPreamble = (~ownerField: string, ~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);
+  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.
+
+**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.
+*/
+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 {
+    | None => "\n  const _owns = () => 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);${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>,
+  ~retiredField: option<string>=?,
+  ~retiredValues: option<array<string>>=?,
+) =>
+  switch (ownerField, retiredField) {
+  | (None, None) => firstResultResponseCode
+  | _ =>
+    let ownerPart = switch ownerField {
+    | None => "\n  const _owns = () => 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);${ownerPart}${retiredPart}
+  const _row = ctx.result.items[0] ?? null;
+  return _owns(_row)${retiredField->Option.isSome ? " && _live(_row)" : ""} ? _row : null;
+}`
+  }
+
 // ---------------------------------------------------------------------------
 // Pipeline resolver pass-through (no before/after processing)
 // ---------------------------------------------------------------------------
@@ -89,7 +333,17 @@ export function response(ctx) {
 // DynamoDB read — by primary key
 // ---------------------------------------------------------------------------
 
-let getItemById =
+// `~ownerField` / `~elevatedGroups` carry the same meaning as on
+// `listAllItemsConnection`, and are optional for the same reason: a state that
+// 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>=[],
+  ~retiredField: option<string>=?,
+  ~retiredValues: option<array<string>>=?,
+) =>
   `${importUtil}
 export function request(ctx) {
   return {
@@ -97,7 +351,7 @@ export function request(ctx) {
     key: { id: util.dynamodb.toDynamoDB(ctx.args.id) }
   };
 }
-${resultResponseCode}
+${ownerScopedResultResponse(~ownerField, ~elevatedGroups, ~retiredField?, ~retiredValues?)}
 `->Pulumi.Input.make
 
 let queryById =
@@ -119,7 +373,39 @@ ${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. */
-let queryItemsWithSortConditions = (sortField: string) =>
+// 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 = (
+  sortField: string,
+  ~ownerField: option<string>=?,
+  ~elevatedGroups: array<string>=[],
+) => {
+  let ownerFilter = switch ownerField {
+  | None => ""
+  | Some(field) =>
+    let elevatedLiteral = elevatedGroups->Array.map(g => `'${g}'`)->Array.join(", ")
+    `
+  // ── owner scoping (generated) ──
+  // Not read from ctx.args, for the reason the list resolver gives: a predicate
+  // deciding what the caller may see must arrive on a channel they cannot name.
+  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);
+  const _ownerFilter = _exempt ? undefined : {
+    expression: '#owner = :owner',
+    expressionNames: { '#owner': '${field}' },
+    expressionValues: { ':owner': util.dynamodb.toDynamoDB(_sub) },
+  };`
+  }
+  let ownerFilterField = switch ownerField {
+  | None => ""
+  | Some(_) => `
+    filter: _ownerFilter,`
+  }
   `${importUtil}
 const encodeCursor = (skValue) => util.base64Encode(skValue);
 const decodeCursor = (cursor) => util.base64Decode(cursor);
@@ -162,10 +448,10 @@ export function request(ctx) {
   const expression = skCondition ? \`#id = :id AND \${skCondition}\` : '#id = :id';
   const orderDesc = filter.order === 'DESC';
   const scanForward = isBackward ? orderDesc : !orderDesc;
-  const pageSize = isBackward ? (args.last ?? 50) : (args.first ?? 50);
+  const pageSize = isBackward ? (args.last ?? 50) : (args.first ?? 50);${ownerFilter}
   return {
     operation: 'Query',
-    query: { expression, expressionNames, expressionValues },
+    query: { expression, expressionNames, expressionValues },${ownerFilterField}
     scanIndexForward: scanForward,
     limit: pageSize + 1,
   };
@@ -194,8 +480,15 @@ export function response(ctx) {
   };
 }
 `->Pulumi.Input.make
+}
 
-let queryByIdSort = (sortField: string) =>
+let queryByIdSort = (
+  sortField: string,
+  ~ownerField: option<string>=?,
+  ~elevatedGroups: array<string>=[],
+  ~retiredField: option<string>=?,
+  ~retiredValues: option<array<string>>=?,
+) =>
   `${importUtil}
 export function request(ctx) {
   return {
@@ -210,7 +503,7 @@ export function request(ctx) {
     }
   };
 }
-${firstResultResponseCode}
+${ownerScopedFirstResultResponse(~ownerField, ~elevatedGroups, ~retiredField?, ~retiredValues?)}
 `->Pulumi.Input.make
 
 // ---------------------------------------------------------------------------
@@ -279,14 +572,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}' },
@@ -297,7 +660,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') {
@@ -312,12 +675,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) {
@@ -325,13 +689,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}',
@@ -351,7 +723,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') {
@@ -366,12 +738,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) {
@@ -379,7 +752,7 @@ export function request(ctx) {
   }
   return result;
 }
-${resultResponseCode}
+${indexConnectionResponseCode}
 `->Pulumi.Input.make
 
 // ---------------------------------------------------------------------------
@@ -893,7 +1266,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) {
@@ -917,10 +1295,98 @@ 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 {
+  | None => "\n  const _owns = () => 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) {
@@ -21,6 +22,125 @@ export function response(ctx) {
 
 let importUtil = `import { util } from '@aws-appsync/utils';`;
 
+function ownerGuardPreamble(ownerField, 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);
+  const _owns = (row) => row == null || _exempt || row['` + ownerField + `'] === _sub;`;
+}
+
+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 {
+    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 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 = () => 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 + `
+  return _owns(ctx.result)` + (
+    Stdlib_Option.isSome(retiredField) ? " && _live(ctx.result)" : ""
+  ) + ` ? ctx.result : null;
+}`;
+}
+
+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 = () => 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 + `
 export function request(ctx) { return {}; }
 ` + resultResponseCode + `
@@ -64,15 +184,18 @@ export function response(ctx) {
 `;
 }
 
-let getItemById = importUtil + `
+function getItemById(ownerField, elevatedGroupsOpt, retiredField, retiredValues) {
+  let elevatedGroups = elevatedGroupsOpt !== undefined ? elevatedGroupsOpt : [];
+  return importUtil + `
 export function request(ctx) {
   return {
     operation: 'GetItem',
     key: { id: util.dynamodb.toDynamoDB(ctx.args.id) }
   };
 }
-` + resultResponseCode + `
+` + ownerScopedResultResponse(ownerField, elevatedGroups, retiredField, retiredValues) + `
 `;
+}
 
 let queryById = importUtil + `
 export function request(ctx) {
@@ -87,7 +210,30 @@ export function request(ctx) {
 ` + resultResponseCode + `
 `;
 
-function queryItemsWithSortConditions(sortField) {
+function queryItemsWithSortConditions(sortField, ownerField, elevatedGroupsOpt) {
+  let elevatedGroups = elevatedGroupsOpt !== undefined ? elevatedGroupsOpt : [];
+  let ownerFilter;
+  if (ownerField !== undefined) {
+    let elevatedLiteral = elevatedGroups.map(g => `'` + g + `'`).join(", ");
+    ownerFilter = `
+  // ── owner scoping (generated) ──
+  // Not read from ctx.args, for the reason the list resolver gives: a predicate
+  // deciding what the caller may see must arrive on a channel they cannot name.
+  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);
+  const _ownerFilter = _exempt ? undefined : {
+    expression: '#owner = :owner',
+    expressionNames: { '#owner': '` + ownerField + `' },
+    expressionValues: { ':owner': util.dynamodb.toDynamoDB(_sub) },
+  };`;
+  } else {
+    ownerFilter = "";
+  }
+  let ownerFilterField = ownerField !== undefined ? `
+    filter: _ownerFilter,` : "";
   return importUtil + `
 const encodeCursor = (skValue) => util.base64Encode(skValue);
 const decodeCursor = (cursor) => util.base64Decode(cursor);
@@ -130,10 +276,10 @@ export function request(ctx) {
   const expression = skCondition ? \`#id = :id AND \${skCondition}\` : '#id = :id';
   const orderDesc = filter.order === 'DESC';
   const scanForward = isBackward ? orderDesc : !orderDesc;
-  const pageSize = isBackward ? (args.last ?? 50) : (args.first ?? 50);
+  const pageSize = isBackward ? (args.last ?? 50) : (args.first ?? 50);` + ownerFilter + `
   return {
     operation: 'Query',
-    query: { expression, expressionNames, expressionValues },
+    query: { expression, expressionNames, expressionValues },` + ownerFilterField + `
     scanIndexForward: scanForward,
     limit: pageSize + 1,
   };
@@ -164,7 +310,8 @@ export function response(ctx) {
 `;
 }
 
-function queryByIdSort(sortField) {
+function queryByIdSort(sortField, ownerField, elevatedGroupsOpt, retiredField, retiredValues) {
+  let elevatedGroups = elevatedGroupsOpt !== undefined ? elevatedGroupsOpt : [];
   return importUtil + `
 export function request(ctx) {
   return {
@@ -179,7 +326,7 @@ export function request(ctx) {
     }
   };
 }
-` + firstResultResponseCode + `
+` + ownerScopedFirstResultResponse(ownerField, elevatedGroups, retiredField, retiredValues) + `
 `;
 }
 
@@ -248,10 +395,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 + `' },
@@ -262,7 +445,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') {
@@ -277,12 +460,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) {
@@ -290,14 +474,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 + `',
@@ -317,7 +502,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') {
@@ -332,12 +517,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) {
@@ -345,7 +531,7 @@ export function request(ctx) {
   }
   return result;
 }
-` + resultResponseCode + `
+` + indexConnectionResponseCode + `
 `;
 }
 
@@ -715,8 +901,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 ?? [];
@@ -739,9 +927,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 = () => 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 + `
@@ -953,6 +1205,13 @@ export {
   firstResultResponseCode,
   resultListResponseCode,
   importUtil,
+  ownerGuardPreamble,
+  exemptPreamble,
+  retiredGuardPreamble,
+  ownerFilterClause,
+  retiredFilterClause,
+  ownerScopedResultResponse,
+  ownerScopedFirstResultResponse,
   pipelinePassThrough,
   nodeDecodeGlobalId,
   nodeGetItemForType,
@@ -963,6 +1222,10 @@ export {
   queryByIndex,
   queryByIndexDeletable,
   queryByIndexSort,
+  indexConnectionResponseCode,
+  indexBackwardPagingGuard,
+  indexCursorPreamble,
+  indexReservedArgs,
   queryByIndexFiltered,
   queryByIndexSortFiltered,
   listAllItems,
@@ -975,6 +1238,7 @@ export {
   resolveIdByIndexSortArgument,
   resolveIds,
   batchGetItemsByIds,
+  refsByIds,
   putItem,
   addItemToList,
   deleteItem,

package/tests/AppSync_Resolver_FunctionsTest.mjs

@@ -16,14 +16,14 @@ describe('Resolver code structure', () => {
   // Labeled ReScript args compile to positional JS args in declaration order.
   const codeValues = [
     ['pipelinePassThrough', F.pipelinePassThrough],
-    ['getItemById', F.getItemById],
+    ['getItemById', F.getItemById(undefined, undefined)],
     ['queryById', F.queryById],
     ['queryByIdSort(sortField)', F.queryByIdSort('status')],
     ['queryByIndex(index)', F.queryByIndex('userId')],
     ['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')],
@@ -54,7 +54,7 @@ describe('Resolver code structure', () => {
 // getItemById
 // ---------------------------------------------------------------------------
 describe('getItemById', () => {
-  const { request, response } = evalResolver(F.getItemById)
+  const { request, response } = evalResolver(F.getItemById(undefined, undefined))
 
   test('request returns GetItem with id key', () => {
     const ctx = makeCtx({ args: { id: 'abc123' } })
@@ -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)
   })
 })
 
@@ -743,3 +758,80 @@ describe('listAllItemsConnection — owner scoping', () => {
     expect(r.filter.expressionValues[':owner']).toEqual({ S: 'ops-1' })
   })
 })
+
+// ---------------------------------------------------------------------------
+// By-key reads — owner scoping
+// ---------------------------------------------------------------------------
+// The list resolver above carried the predicate while these did not, so a caller
+// narrowed to their own rows could still read any row they could name. These
+// cases pin the guard in the place it has to live: the response, since a GetItem
+// has no FilterExpression, and null rather than an error, which is what the
+// in-process platform answers and what does not confirm the row exists.
+describe('getItemById / queryByIdSort — owner scoping', () => {
+  const asUser = (sub, groups = []) => ({
+    username: sub,
+    sub,
+    sourceIp: [],
+    claims: { 'cognito:groups': groups },
+  })
+  const row = { id: 'ord-1', customerId: 'cust-a', total: 10 }
+
+  const getScoped = () => evalResolver(F.getItemById('customerId', ['Admin']))
+  const sortScoped = () => evalResolver(F.queryByIdSort('status', 'customerId', ['Admin']))
+
+  test('an owner reads their own row', () => {
+    const { response } = getScoped()
+    expect(response(makeCtx({ result: row, identity: asUser('cust-a') }))).toEqual(row)
+  })
+
+  test('a foreign row reads as null, not as an error', () => {
+    const { response } = getScoped()
+    expect(response(makeCtx({ result: row, identity: asUser('cust-b') }))).toBeNull()
+  })
+
+  test('an elevated caller reads any row', () => {
+    const { response } = getScoped()
+    expect(response(makeCtx({ result: row, identity: asUser('ops-1', ['Admin']) }))).toEqual(row)
+  })
+
+  test('an IAM-shaped identity with no sub is exempt, not compared against undefined', () => {
+    const { response } = getScoped()
+    const iam = { username: 'svc', userArn: 'arn:aws:iam::1:role/r', sourceIp: [] }
+    expect(response(makeCtx({ result: row, identity: iam }))).toEqual(row)
+  })
+
+  test('a wholly absent identity is exempt rather than a crash', () => {
+    const { response } = getScoped()
+    expect(response(makeCtx({ result: row, identity: null }))).toEqual(row)
+  })
+
+  test('a missing row stays null and does not fall into the ownership branch', () => {
+    const { response } = getScoped()
+    expect(response(makeCtx({ result: null, identity: asUser('cust-b') }))).toBeNull()
+  })
+
+  test('a view with no owner field is never scoped', () => {
+    const { response } = evalResolver(F.getItemById(undefined, []))
+    expect(response(makeCtx({ result: row, identity: asUser('cust-b') }))).toEqual(row)
+  })
+
+  test('queryByIdSort narrows its first row the same way', () => {
+    const { response } = sortScoped()
+    const ctxFor = sub => makeCtx({ result: { items: [row] }, identity: asUser(sub) })
+    expect(response(ctxFor('cust-a'))).toEqual(row)
+    expect(response(ctxFor('cust-b'))).toBeNull()
+  })
+
+  test('queryItemsWithSortConditions scopes in the REQUEST, so the page is cut after narrowing', () => {
+    const { request } = evalResolver(
+      F.queryItemsWithSortConditions('createdAt', 'customerId', ['Admin']),
+    )
+    const scoped = request(makeCtx({ args: { id: 'ord-1' }, identity: asUser('cust-a') }))
+    expect(scoped.filter.expression).toBe('#owner = :owner')
+    expect(scoped.filter.expressionValues[':owner']).toEqual({ S: 'cust-a' })
+    const elevated = request(
+      makeCtx({ args: { id: 'ord-1' }, identity: asUser('ops-1', ['Admin']) }),
+    )
+    expect(elevated.filter).toBeUndefined()
+  })
+})