@reventlessdev/reventless-aws 3.0.0-alpha.305 → 3.0.0-alpha.307

package/src/adapter/QueryDb/QueryDbResolvers_AppSync.res

@@ -4,7 +4,7 @@ open PulumiAws.AppSync
 // `NotFoundException: No field named X` (the schema-propagation race) with
 // exponential backoff. Replaces AppSync_Resolver_Native (aws-native provider)
 // which exhibited the same race in production.
-// See docs/plans/appsync-resolver-aws-native-retry.md.
+// See docs/plans/done/appsync-resolver-aws-native-retry.md.
 module Resolver = AppSync_Resolver_Retrying
 open Reventless.ReadModel
 
@@ -55,7 +55,7 @@ export function response(ctx) {
     that carry no `name`. Returning `Some(attr)` makes the Connection Scan emit an
     `attribute_exists(#attr)` filter so those rows never reach the non-null GraphQL schema.
     `name` is the already-capitalized read-model name (spec name, e.g. "Plugins").
-    See docs/plans/platform-plugins-admin-connection-null-rows.md. */
+    See docs/plans/done/platform-plugins-admin-connection-null-rows.md. */
 let internalRowRequiredAttr = (name: string): option<string> =>
   name == "Plugins" ? Some("name") : None
 
@@ -69,7 +69,7 @@ let make: ReventlessCore.QueryDb_Adapter.resolversMaker<api, role> = (
   ~idResolverConfigs: array<idResolverConfig>,
   ~idsResolverConfigs: array<idsResolverConfig>,
   // AWS path enforces authorization via `@aws_cognito_user_pools(cognito_groups: …)` on the
-  // SDL fields (see Stage E in docs/plans/host-ui-login-core.md). Accepted but
+  // SDL fields (see Stage E in docs/plans/done/host-ui-login-core.md). Accepted but
   // ignored here so the in-memory and AWS resolver maker signatures stay aligned.
   ~authorization as _: Reventless.Authorization.permission,
   ~opts,
@@ -167,13 +167,55 @@ let make: ReventlessCore.QueryDb_Adapter.resolversMaker<api, role> = (
   // This prevents a race condition where AppSync resolvers are deployed before
   // the schema push completes and the new fields are ACTIVE in AppSync.
   let resourcesMaker: ReventlessCore.QueryDb.resolversResourcesMaker = allQueryDbs => {
+    // The state's `@owner` field, derived from the same schema `capability` is
+    // derived from, so the two cannot disagree about this read model's fields.
+    //
+    // Read HERE, at the top, rather than beside the list resolver that first
+    // needed it. The by-id resolvers are built a few lines below and the lookup
+    // used to sit well after them, so they were generated without it: a list
+    // narrowed to the caller beside a by-id read that hands over any row it is
+    // asked for. That is not a partial delivery — the row is reachable by
+    // anyone who can name one, and the list gives no sign of it, because the
+    // list is correct.
+    let stateSchemaOpt = ReventlessCore.Plugin_Helpers.stateSchemaRegistry->Dict.get(name)
+    let ownerField = switch stateSchemaOpt {
+    | Some(s) => Reventless.Owner.fieldNames(s)->Array.get(0)
+    | None => None
+    }
+    let elevatedGroups = Reventless.OwnerScope.elevatedGroups()
+
+    // Read here for exactly the reason `ownerField` above is, and after making
+    // the same mistake: the by-id, by-ids and by-index resolvers are built below
+    // and this lookup used to sit past all of them, so they were generated
+    // without a retirement predicate — a list that withheld archived rows beside
+    // by-key doors that handed any one of them over on request.
+    let retiredSpec =
+      stateSchemaOpt
+      ->Option.flatMap(Reventless.StateAnnotations.getSpec)
+      ->Option.flatMap(spec => spec.retired)
+    let retiredField = retiredSpec->Option.map(r => r.field)
+    let retiredValues = retiredSpec->Option.flatMap(r => r.values)
+
     let resolverByIdSingle = if includeIdParam {
       makeQueryResolver(
         ~resolverName=fieldNameForSingle->String.capitalize,
         ~field=fieldNameForSingle->Pulumi.Input.make,
         ~code=switch subIdField {
-        | Some(sortField) => Resolver.Functions.queryByIdSort(sortField)
-        | None => Resolver.Functions.getItemById
+        | Some(sortField) =>
+          Resolver.Functions.queryByIdSort(
+            sortField,
+            ~ownerField?,
+            ~elevatedGroups,
+            ~retiredField?,
+            ~retiredValues?,
+          )
+        | None =>
+          Resolver.Functions.getItemById(
+            ~ownerField?,
+            ~elevatedGroups,
+            ~retiredField?,
+            ~retiredValues?,
+          )
         },
       )
     } else {
@@ -188,7 +230,11 @@ let make: ReventlessCore.QueryDb_Adapter.resolversMaker<api, role> = (
         makeQueryResolver(
           ~resolverName=fieldNameForSingle->String.capitalize ++ "Items",
           ~field=(fieldNameForSingle ++ "Items")->Pulumi.Input.make,
-          ~code=Resolver.Functions.queryItemsWithSortConditions(sortField),
+          ~code=Resolver.Functions.queryItemsWithSortConditions(
+            sortField,
+            ~ownerField?,
+            ~elevatedGroups,
+          ),
         )
       )
     } else {
@@ -203,7 +249,6 @@ let make: ReventlessCore.QueryDb_Adapter.resolversMaker<api, role> = (
     // registered or has no indexable fields — the resolver template emits the same
     // SDL the in-memory adapter does, so the AWS Filter / OrderBy stays in lockstep
     // with the SDL emitted by GraphQL_FragmentGenerator at runtime.
-    let stateSchemaOpt = ReventlessCore.Plugin_Helpers.stateSchemaRegistry->Dict.get(name)
     let capability = switch stateSchemaOpt {
     | Some(s) => ReventlessCore.GraphQL_FragmentGenerator.deriveServerCapability(~entityName=name, s)
     | None => ReventlessCore.GraphQL_FragmentGenerator.emptyCapability
@@ -236,14 +281,8 @@ let make: ReventlessCore.QueryDb_Adapter.resolversMaker<api, role> = (
     // resolves `name: String!` to null → non-null violation that nulls the entire
     // Platform_PluginConnection. Exclude them with an `attribute_exists(#name)` filter
     // (prefix-agnostic: real plugin rows always carry `name`, internal rows never do).
-    // See docs/plans/platform-plugins-admin-connection-null-rows.md.
+    // See docs/plans/done/platform-plugins-admin-connection-null-rows.md.
     let requireAttribute = internalRowRequiredAttr(name)
-    // Derived from the same schema `capability` came from, so the two cannot
-    // disagree about this read model's fields.
-    let ownerField = switch stateSchemaOpt {
-    | Some(s) => Reventless.Owner.fieldNames(s)->Array.get(0)
-    | None => None
-    }
     // A DynamoDB FilterExpression is applied AFTER the page is read, so a scoped
     // list over a table with no index on the owner field returns short pages —
     // correct, but pathological once a caller owns a small fraction of the rows.
@@ -271,12 +310,6 @@ let make: ReventlessCore.QueryDb_Adapter.resolversMaker<api, role> = (
       }
     | None => ()
     }
-    let retiredSpec =
-      stateSchemaOpt
-      ->Option.flatMap(Reventless.StateAnnotations.getSpec)
-      ->Option.flatMap(spec => spec.retired)
-    let retiredField = retiredSpec->Option.map(r => r.field)
-    let retiredValues = retiredSpec->Option.flatMap(r => r.values)
     // The same class of "works, but scans" mistake as the owner warning above,
     // and the retirement case degrades the same way: the FilterExpression is
     // applied after the page is read, so pages shrink as the archive's share of
@@ -310,7 +343,7 @@ let make: ReventlessCore.QueryDb_Adapter.resolversMaker<api, role> = (
           ~sortFields=sortFieldNames,
           ~requireAttribute?,
           ~ownerField?,
-          ~elevatedGroups=Reventless.OwnerScope.elevatedGroups(),
+          ~elevatedGroups,
           ~retiredField?,
           ~retiredValues?,
         )
@@ -319,26 +352,16 @@ let make: ReventlessCore.QueryDb_Adapter.resolversMaker<api, role> = (
       },
     )
     let resolversByIndex = indexes->Array.map(({index} as indexConfig) => {
-      // Strip a leading "by" from the index name before capitalizing to avoid
-      // double "By" in the generated field name (e.g. index "byPlugin" → "ByPlugin",
-      // not "ByByPlugin"). Uses the plugin-prefixed fieldNameForSingle so the
-      // resolver name is properly namespaced (e.g. "schemaHistoryByPlugin", not
-      // "SchemaHistoryByByPlugin" from the raw entity name).
-      let stripLeadingBy = s =>
-        if s->String.startsWith("by") && s->String.length > 2 {
-          s->String.slice(~start=2, ~end=s->String.length)
-        } else {
-          s
-        }
-      let resolverName =
-        fieldNameForSingle->String.capitalize ++
-        "By" ++
-        (index->stripLeadingBy->String.capitalize)
-      let fieldName =
-        fieldNameForSingle ++
-        "By" ++
-        (index->stripLeadingBy->String.capitalize)
-      let idField = indexConfig.idField->Option.getOr(index)
+      // Name and key field both come from `GraphQL_FragmentGenerator`, which is
+      // where the SDL field this attaches to is derived. Deriving them here as
+      // well is how the two came to disagree: the emitted field declared `id`
+      // while this resolver read the index key, so the door could not be called.
+      let fieldName = ReventlessCore.GraphQL_FragmentGenerator.indexQueryFieldName(
+        ~singleFieldName=fieldNameForSingle,
+        ~index,
+      )
+      let resolverName = fieldName->String.capitalize
+      let idField = ReventlessCore.GraphQL_FragmentGenerator.indexKeyField(indexConfig)
       switch indexConfig.authorization {
       | None =>
         makeQueryResolver(
@@ -346,8 +369,24 @@ let make: ReventlessCore.QueryDb_Adapter.resolversMaker<api, role> = (
           ~field=fieldName->Pulumi.Input.make,
           ~code=switch indexConfig.subIdField {
           | Some(sortField) =>
-            Resolver.Functions.queryByIndexSortFiltered(~index, ~idField, ~sortField)
-          | None => Resolver.Functions.queryByIndexFiltered(~index, ~idField)
+            Resolver.Functions.queryByIndexSortFiltered(
+              ~index,
+              ~idField,
+              ~sortField,
+              ~ownerField?,
+              ~retiredField?,
+              ~retiredValues?,
+              ~elevatedGroups,
+            )
+          | None =>
+            Resolver.Functions.queryByIndexFiltered(
+              ~index,
+              ~idField,
+              ~ownerField?,
+              ~retiredField?,
+              ~retiredValues?,
+              ~elevatedGroups,
+            )
           },
         )
       | Some({tableName, group}) =>
@@ -373,7 +412,20 @@ let make: ReventlessCore.QueryDb_Adapter.resolversMaker<api, role> = (
           ~name=resolverName,
           ~api,
           ~dataSource=dataSourceName,
-          ~code=Resolver.Functions.queryByIndexFiltered(~index, ~idField),
+          // No `~ownerField`, deliberately: this index declares its own
+          // authorization, and the rows it grants a group member are by
+          // construction owned by somebody else — an order assigned to a
+          // fulfilment operator belongs to the customer who placed it. Adding the
+          // owner predicate here would return nothing and revoke the access the
+          // auth table exists to grant. Retirement still applies: an archived row
+          // is withdrawn from everyone who has not asked, whoever owns it.
+          ~code=Resolver.Functions.queryByIndexFiltered(
+            ~index,
+            ~idField,
+            ~retiredField?,
+            ~retiredValues?,
+            ~elevatedGroups,
+          ),
           ~opts,
         )
         // The interceptor leads the chain, as it does in every other Query
@@ -426,7 +478,43 @@ let make: ReventlessCore.QueryDb_Adapter.resolversMaker<api, role> = (
           ~field=byIdsField->Pulumi.Input.make,
           ~code=generateCode(
             ~storageResource=storage,
-            ~template=Resolver.Functions.batchGetItemsByIds,
+            ~template=Resolver.Functions.batchGetItemsByIds(
+              ~ownerField?,
+              ~retiredField?,
+              ~retiredValues?,
+              ~elevatedGroups,
+            ),
+          ),
+        ),
+      )
+    } else {
+      None
+    }
+
+    // The reference door. Registered under the same conditions as by-ids because
+    // it is the same read; what differs is the projection on the way out, and
+    // that a view which named its retired rows lets them through it.
+    //
+    // Not conditional on the annotation: `GraphQL_FragmentGenerator` emits the
+    // field for every view — one SDL serves every backend — so a view without a
+    // resolver here would be a field that errors rather than one that is absent.
+    let resolverRefs = if includeIdParam && subIdField === None {
+      let storage = storageResource(~pluginName=None, ~tableName=name)
+      let refsField = fieldNameForAll ++ "Refs"
+      Some(
+        makeQueryResolver(
+          ~resolverName=refsField->String.capitalize,
+          ~field=refsField->Pulumi.Input.make,
+          ~code=generateCode(
+            ~storageResource=storage,
+            ~template=Resolver.Functions.refsByIds(
+              ~labelField,
+              ~retiredField,
+              ~retiredValues,
+              ~namedWhenRetired=retiredSpec->Option.mapOr(false, r => r.namedWhenRetired),
+              ~ownerField?,
+              ~elevatedGroups,
+            ),
           ),
         ),
       )
@@ -521,7 +609,11 @@ let make: ReventlessCore.QueryDb_Adapter.resolversMaker<api, role> = (
     | (None, Some(byIds)) => [resolverByIdSingle, resolverAll, byIds]
     | (None, None) => [resolverByIdSingle, resolverAll]
     }
-    Array.flat([mainResolvers, resolversByIndex, idResolvers, idsResolvers])
+    // Appended rather than folded into `mainResolvers`' four-way switch: the door
+    // is independent of whether this view has a sub-id door, and adding a third
+    // dimension to that match would spell eight cases to say one thing.
+    let refsResolvers = resolverRefs->Option.mapOr([], r => [r])
+    Array.flat([mainResolvers, refsResolvers, resolversByIndex, idResolvers, idsResolvers])
     ->Array.map(Util.AppSync.toResourceNative)
   }
 

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

@@ -91,10 +91,15 @@ function make(name, api, apiRole, dataSourceName, indexes, subIdField, idResolve
   };
   let fieldNameForAll = registryEntry !== undefined ? registryEntry.listFieldName : name$1 + "s";
   let resourcesMaker = allQueryDbs => {
-    let resolverByIdSingle = includeIdParam ? makeQueryResolver(Stdlib_String.capitalize(fieldNameForSingle), fieldNameForSingle, subIdField !== undefined ? AppSync_Resolver_Functions$PulumiAws.queryByIdSort(subIdField) : AppSync_Resolver_Functions$PulumiAws.getItemById) : makeQueryResolver(Stdlib_String.capitalize(fieldNameForSingle), fieldNameForSingle, AppSync_Resolver_Functions$PulumiAws.listAllItems);
-    let resolverByIdMultiple = includeIdParam ? Stdlib_Option.map(subIdField, sortField => makeQueryResolver(Stdlib_String.capitalize(fieldNameForSingle) + "Items", fieldNameForSingle + "Items", AppSync_Resolver_Functions$PulumiAws.queryItemsWithSortConditions(sortField))) : undefined;
-    let labelField = registryEntry !== undefined ? Stdlib_Option.getOr(registryEntry.labelField, "id") : "id";
     let stateSchemaOpt = Plugin_Helpers$ReventlessCore.stateSchemaRegistry[name$1];
+    let ownerField = stateSchemaOpt !== undefined ? Owner$Reventless.fieldNames(stateSchemaOpt)[0] : undefined;
+    let elevatedGroups = OwnerScope$Reventless.elevatedGroups();
+    let retiredSpec = Stdlib_Option.flatMap(Stdlib_Option.flatMap(stateSchemaOpt, StateAnnotations$Reventless.getSpec), spec => spec.retired);
+    let retiredField = Stdlib_Option.map(retiredSpec, r => r.field);
+    let retiredValues = Stdlib_Option.flatMap(retiredSpec, r => r.values);
+    let resolverByIdSingle = includeIdParam ? makeQueryResolver(Stdlib_String.capitalize(fieldNameForSingle), fieldNameForSingle, subIdField !== undefined ? AppSync_Resolver_Functions$PulumiAws.queryByIdSort(subIdField, ownerField, elevatedGroups, retiredField, retiredValues) : AppSync_Resolver_Functions$PulumiAws.getItemById(ownerField, elevatedGroups, retiredField, retiredValues)) : makeQueryResolver(Stdlib_String.capitalize(fieldNameForSingle), fieldNameForSingle, AppSync_Resolver_Functions$PulumiAws.listAllItems);
+    let resolverByIdMultiple = includeIdParam ? Stdlib_Option.map(subIdField, sortField => makeQueryResolver(Stdlib_String.capitalize(fieldNameForSingle) + "Items", fieldNameForSingle + "Items", AppSync_Resolver_Functions$PulumiAws.queryItemsWithSortConditions(sortField, ownerField, elevatedGroups))) : undefined;
+    let labelField = registryEntry !== undefined ? Stdlib_Option.getOr(registryEntry.labelField, "id") : "id";
     let capability = stateSchemaOpt !== undefined ? GraphQL_FragmentGenerator$ReventlessCore.deriveServerCapability(name$1, stateSchemaOpt) : GraphQL_FragmentGenerator$ReventlessCore.emptyCapability;
     let filterFieldNames = capability.filterFields.map(f => f.name);
     let rangeFieldNames = Stdlib_Array.filterMap(capability.filterFields, f => {
@@ -110,7 +115,6 @@ function make(name, api, apiRole, dataSourceName, indexes, subIdField, idResolve
       GraphQL_FragmentGenerator$ReventlessCore.validateScanSortAlignment(stateSchemaOpt, name$1, knownSortFields).forEach(msg => log.warn("QueryDbResolvers_AppSync", undefined, msg));
     }
     let requireAttribute = internalRowRequiredAttr(name$1);
-    let ownerField = stateSchemaOpt !== undefined ? Owner$Reventless.fieldNames(stateSchemaOpt)[0] : undefined;
     OwnerScopeDiagnostics$ReventlessCore.warnIfNoElevatedGroups("QueryDbResolvers_AppSync", name$1, ownerField);
     let isIndexed = f => {
       if (indexes.some(ic => Stdlib_Option.getOr(ic.idField, ic.index) === f)) {
@@ -122,30 +126,20 @@ function make(name, api, apiRole, dataSourceName, indexes, subIdField, idResolve
     if (ownerField !== undefined && !isIndexed(ownerField)) {
       log.warn("QueryDbResolvers_AppSync", undefined, name$1 + `: @owner field "` + ownerField + `" is not the key of any index on this table. ` + "Owner-scoped reads will Scan and filter, so pages shrink as the caller's share of the rows falls. Add an @index on that field before this read model grows.");
     }
-    let retiredSpec = Stdlib_Option.flatMap(Stdlib_Option.flatMap(stateSchemaOpt, StateAnnotations$Reventless.getSpec), spec => spec.retired);
-    let retiredField = Stdlib_Option.map(retiredSpec, r => r.field);
-    let retiredValues = Stdlib_Option.flatMap(retiredSpec, r => r.values);
     if (retiredField !== undefined && !isIndexed(retiredField)) {
       log.warn("QueryDbResolvers_AppSync", undefined, name$1 + `: @retired field "` + retiredField + `" is not the key of any index on this table. ` + "Reads that exclude retired rows will Scan and filter, so pages shrink as the archive's share of the rows grows. Add an @index on that field before this read model grows.");
     }
-    let resolverAll = makeQueryResolver(Stdlib_String.capitalize(fieldNameForAll), fieldNameForAll, connectionSpec ? AppSync_Resolver_Functions$PulumiAws.listAllItemsConnection(labelField, filterFieldNames, rangeFieldNames, sortFieldNames, requireAttribute, ownerField, OwnerScope$Reventless.elevatedGroups(), retiredField, retiredValues) : AppSync_Resolver_Functions$PulumiAws.listAllItems);
+    let resolverAll = makeQueryResolver(Stdlib_String.capitalize(fieldNameForAll), fieldNameForAll, connectionSpec ? AppSync_Resolver_Functions$PulumiAws.listAllItemsConnection(labelField, filterFieldNames, rangeFieldNames, sortFieldNames, requireAttribute, ownerField, elevatedGroups, retiredField, retiredValues) : AppSync_Resolver_Functions$PulumiAws.listAllItems);
     let resolversByIndex = indexes.map(indexConfig => {
       let index = indexConfig.index;
-      let stripLeadingBy = s => {
-        if (s.startsWith("by") && s.length > 2) {
-          return s.slice(2, s.length);
-        } else {
-          return s;
-        }
-      };
-      let resolverName = Stdlib_String.capitalize(fieldNameForSingle) + "By" + Stdlib_String.capitalize(stripLeadingBy(index));
-      let fieldName = fieldNameForSingle + "By" + Stdlib_String.capitalize(stripLeadingBy(index));
-      let idField = Stdlib_Option.getOr(indexConfig.idField, index);
+      let fieldName = GraphQL_FragmentGenerator$ReventlessCore.indexQueryFieldName(fieldNameForSingle, index);
+      let resolverName = Stdlib_String.capitalize(fieldName);
+      let idField = GraphQL_FragmentGenerator$ReventlessCore.indexKeyField(indexConfig);
       let match = indexConfig.authorization;
       if (match !== undefined) {
         let authDataSource = AppSync_DataSource$PulumiAws.makeDynamoDBDataSourceWithTableName(resolverName + "Auth", api, Util_DynamoDb$ReventlessAws.findResource(Util_QueryDb$ReventlessCore.getLocalStorageResources(allQueryDbs, match.tableName)).name, apiRole, opts);
         let authFunction = AppSync_Function$PulumiAws.makeJs(resolverName + "Auth", api, authDataSource.name, AppSync_Resolver_Functions$PulumiAws.authorizeIndexedAccess(index, match.group), opts);
-        let queryFunction = AppSync_Function$PulumiAws.makeJs(resolverName, api, dataSourceName, AppSync_Resolver_Functions$PulumiAws.queryByIndexFiltered(index, idField), opts);
+        let queryFunction = AppSync_Function$PulumiAws.makeJs(resolverName, api, dataSourceName, AppSync_Resolver_Functions$PulumiAws.queryByIndexFiltered(index, idField, undefined, retiredField, retiredValues, elevatedGroups), opts);
         let interceptorFn = interceptorFunction(resolverName);
         return AppSync_Resolver_Retrying$ReventlessAws.makePipelineJsResolver(resolverName, api, "Query", fieldName, AppSync_Resolver_Functions$PulumiAws.pipelinePassThrough, interceptorFn !== undefined ? [
             interceptorFn,
@@ -157,7 +151,7 @@ function make(name, api, apiRole, dataSourceName, indexes, subIdField, idResolve
           ], opts);
       }
       let sortField = indexConfig.subIdField;
-      return makeQueryResolver(resolverName, fieldName, sortField !== undefined ? AppSync_Resolver_Functions$PulumiAws.queryByIndexSortFiltered(index, idField, sortField) : AppSync_Resolver_Functions$PulumiAws.queryByIndexFiltered(index, idField));
+      return makeQueryResolver(resolverName, fieldName, sortField !== undefined ? AppSync_Resolver_Functions$PulumiAws.queryByIndexSortFiltered(index, idField, ownerField, sortField, retiredField, retiredValues, elevatedGroups) : AppSync_Resolver_Functions$PulumiAws.queryByIndexFiltered(index, idField, ownerField, retiredField, retiredValues, elevatedGroups));
     });
     let storageResource = (pluginName, tableName) => Adapter$ReventlessCore.outputToResource(Util_DynamoDb$ReventlessAws.findResourceInOutput(Plugin_Helpers$ReventlessCore.getStorageResources(allQueryDbs, pluginName, tableName)));
     let generateCode = (storageResource, template) => storageResource.name.apply(realTableName => template(realTableName));
@@ -165,10 +159,18 @@ function make(name, api, apiRole, dataSourceName, indexes, subIdField, idResolve
     if (includeIdParam && subIdField === undefined) {
       let storage = storageResource(undefined, name$1);
       let byIdsField = fieldNameForAll + "ByIds";
-      resolverByIds = makeQueryResolver(Stdlib_String.capitalize(byIdsField), byIdsField, generateCode(storage, AppSync_Resolver_Functions$PulumiAws.batchGetItemsByIds));
+      resolverByIds = makeQueryResolver(Stdlib_String.capitalize(byIdsField), byIdsField, generateCode(storage, AppSync_Resolver_Functions$PulumiAws.batchGetItemsByIds(ownerField, retiredField, retiredValues, elevatedGroups)));
     } else {
       resolverByIds = undefined;
     }
+    let resolverRefs;
+    if (includeIdParam && subIdField === undefined) {
+      let storage$1 = storageResource(undefined, name$1);
+      let refsField = fieldNameForAll + "Refs";
+      resolverRefs = makeQueryResolver(Stdlib_String.capitalize(refsField), refsField, generateCode(storage$1, AppSync_Resolver_Functions$PulumiAws.refsByIds(labelField, retiredField, retiredValues, Stdlib_Option.mapOr(retiredSpec, false, r => r.namedWhenRetired), ownerField, elevatedGroups)));
+    } else {
+      resolverRefs = undefined;
+    }
     let idResolvers = idResolverConfigs.map(config => {
       let target = config.target;
       let targetId = target.idField;
@@ -251,8 +253,10 @@ function make(name, api, apiRole, dataSourceName, indexes, subIdField, idResolve
             resolverAll
           ]
       );
+    let refsResolvers = Stdlib_Option.mapOr(resolverRefs, [], r => [r]);
     return [
       mainResolvers,
+      refsResolvers,
       resolversByIndex,
       idResolvers,
       idsResolvers

package/src/adapter/QueryDb/QueryDbResolvers_Lambda.res

@@ -9,7 +9,7 @@
 //
 // Field names / includeIdParam / connectionSpec come from the same registry the
 // AppSync path reads, so the SDL emitted by GraphQL_FragmentGenerator stays in
-// lockstep. Kinds covered: getById, list (connection), index, byIds. Deferred to
+// lockstep. Kinds covered: getById, list (connection), index, byIds, refs. Deferred to
 // B3.2c: items (sub-id connection), @resolves/@resolvesMany, node, auth-table.
 
 module Resolver = AppSync_Resolver_Retrying
@@ -150,13 +150,6 @@ let make: ReventlessCore.QueryDb_Adapter.resolversMaker<api, role> = (
       ~opts,
     )
 
-  let stripLeadingBy = s =>
-    if s->String.startsWith("by") && s->String.length > 2 {
-      s->String.slice(~start=2, ~end=s->String.length)
-    } else {
-      s
-    }
-
   // Resolvers are deferred into resourcesMaker (created inside the schema-pushed
   // builderOutputs.apply, like the AppSync path) — so they only exist after the
   // fields are ACTIVE and after PgQueryResolver_Builder.provision has resolved
@@ -202,14 +195,28 @@ let make: ReventlessCore.QueryDb_Adapter.resolversMaker<api, role> = (
       []
     }
 
+    // The reference door — {list}Refs(ids). Same shape as by-ids and registered
+    // under the same conditions, because it is the same read: a set of keys in,
+    // rows out. What differs is on the way out, where the row is projected to
+    // what a reference needs and a retirement is lifted for a view that named its
+    // rows.
+    let refs = if includeIdParam && subIdField === None {
+      let refsField = fieldNameForAll ++ "Refs"
+      [mkResolver(~resolverName=refsField->String.capitalize, ~field=refsField, ~kind="refs")]
+    } else {
+      []
+    }
+
     // Per-index equality queries: {single}By{Index}. A group-restricted index
     // (indexConfig.authorization) bakes the auth-table pipeline params — the
     // Lambda verifies group membership + ownership against the auth read model.
     let byIndex = indexes->Array.map((ic: indexConfig) => {
       let index = ic.index
-      let resolverName =
-        fieldNameForSingle->String.capitalize ++ "By" ++ index->stripLeadingBy->String.capitalize
-      let field = fieldNameForSingle ++ "By" ++ index->stripLeadingBy->String.capitalize
+      let field = ReventlessCore.GraphQL_FragmentGenerator.indexQueryFieldName(
+        ~singleFieldName=fieldNameForSingle,
+        ~index,
+      )
+      let resolverName = field->String.capitalize
       switch ic.authorization {
       | Some({tableName, group}) =>
         mkResolver(
@@ -278,6 +285,7 @@ let make: ReventlessCore.QueryDb_Adapter.resolversMaker<api, role> = (
     [byId, all]
     ->Array.concat(items)
     ->Array.concat(byIds)
+    ->Array.concat(refs)
     ->Array.concat(byIndex)
     ->Array.concat(idResolvers)
     ->Array.concat(idsResolvers)

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

@@ -7,6 +7,7 @@ import * as Plugin_Helpers$ReventlessCore from "@reventlessdev/reventless-core/s
 import * as AppSync_Resolver_Functions$PulumiAws from "@reventlessdev/rescript-pulumi-aws/src/AppSync/AppSync_Resolver_Functions.res.mjs";
 import * as PgQueryResolver_Builder$ReventlessAws from "./PgQueryResolver_Builder.res.mjs";
 import * as AppSync_Resolver_Retrying$ReventlessAws from "../Api/AppSync_Resolver_Retrying.res.mjs";
+import * as GraphQL_FragmentGenerator$ReventlessCore from "@reventlessdev/reventless-core/src/components/Api/GraphQL_FragmentGenerator.res.mjs";
 
 let identityBlock = `id != null && id.sub != null
       ? { userId: id.sub, username: id.username, groups: id.claims?.['cognito:groups'] ?? [], claims: id.claims, provider: 'Cognito' }
@@ -77,13 +78,6 @@ function make(name, api, param, dataSourceName, indexes, subIdField, idResolverC
     PgQueryResolver_Builder$ReventlessAws.registerNodeType(returnTypeName, name$1);
   }
   let mkResolver = (resolverName, field, kind, index, authTable, authGroup) => AppSync_Resolver_Retrying$ReventlessAws.makeUnitJsResolver(resolverName, api, dataSourceName, "Query", field, invokeTemplate(name$1, kind, index, authTable, authGroup), opts);
-  let stripLeadingBy = s => {
-    if (s.startsWith("by") && s.length > 2) {
-      return s.slice(2, s.length);
-    } else {
-      return s;
-    }
-  };
   let resourcesMaker = _allQueryDbs => {
     let byId = mkResolver(Stdlib_String.capitalize(fieldNameForSingle), fieldNameForSingle, includeIdParam ? "getById" : "list", undefined, undefined, undefined);
     let all = mkResolver(Stdlib_String.capitalize(fieldNameForAll), fieldNameForAll, "list", undefined, undefined, undefined);
@@ -95,10 +89,17 @@ function make(name, api, param, dataSourceName, indexes, subIdField, idResolverC
     } else {
       byIds = [];
     }
+    let refs;
+    if (includeIdParam && subIdField === undefined) {
+      let refsField = fieldNameForAll + "Refs";
+      refs = [mkResolver(Stdlib_String.capitalize(refsField), refsField, "refs", undefined, undefined, undefined)];
+    } else {
+      refs = [];
+    }
     let byIndex = indexes.map(ic => {
       let index = ic.index;
-      let resolverName = Stdlib_String.capitalize(fieldNameForSingle) + "By" + Stdlib_String.capitalize(stripLeadingBy(index));
-      let field = fieldNameForSingle + "By" + Stdlib_String.capitalize(stripLeadingBy(index));
+      let field = GraphQL_FragmentGenerator$ReventlessCore.indexQueryFieldName(fieldNameForSingle, index);
+      let resolverName = Stdlib_String.capitalize(field);
       let match = ic.authorization;
       if (match !== undefined) {
         return mkResolver(resolverName, field, "index", index, Stdlib_String.capitalize(match.tableName), match.group);
@@ -150,7 +151,7 @@ function make(name, api, param, dataSourceName, indexes, subIdField, idResolverC
     return [
       byId,
       all
-    ].concat(items).concat(byIds).concat(byIndex).concat(idResolvers).concat(idsResolvers).map(Util_AppSync$ReventlessAws.toResourceNative);
+    ].concat(items).concat(byIds).concat(refs).concat(byIndex).concat(idResolvers).concat(idsResolvers).map(Util_AppSync$ReventlessAws.toResourceNative);
   };
   return {
     resources: [],

package/src/adapter/QueryEngine/QueryEngine_DynamoDb.res

@@ -147,7 +147,7 @@ let make: ReventlessCore.QueryDb_Adapter.queryEngineMaker = allQueryDbs => {
   // B3.1: Postgres-backed read models have NO DynamoDB resource — exclude them
   // instead of failing findResource at deploy time. They are not reachable via
   // this engine (getRuntimeResource raises its explicit not-found error at
-  // query time); see docs/plans/aws-postgres-querydb-adapter.md § B3.1b.
+  // query time); see docs/plans/done/aws-postgres-querydb-adapter.md § B3.1b.
   let dynamoDbQueryDbs =
     allQueryDbs
     ->Dict.toArray

package/src/adapter/Runtime/AggregateEntryPoint.mjs

@@ -22,7 +22,7 @@ import { commandOutcomeToJson, runInlineAndCollect } from "@reventlessdev/revent
 import { handleQueueEvent, publishJsons as sqsPublishJsons } from "@reventlessdev/reventless-aws/src/adapter/CommandTopic/CommandTopicChannel_SQS_Runtime.res.mjs";
 // Typed cold-start core — EventLog storage-ops selection/wiring, compiler-checked
 // against the framework signatures (see the module header and
-// docs/plans/minimize-lambda-entrypoint-mjs-shell.md).
+// docs/plans/done/minimize-lambda-entrypoint-mjs-shell.md).
 import { makeStorageOps } from "./AggregateEntryPoint_Ops.res.mjs";
 import { DynamoDBClient, ScanCommand } from "@aws-sdk/client-dynamodb";
 import { unmarshall } from "@aws-sdk/util-dynamodb";

package/src/adapter/Runtime/AggregateEntryPoint_Ops.res

@@ -1,6 +1,6 @@
 // Typed cold-start core for the Aggregate Lambda entry point.
 //
-// The "typed core, thin shell" split (docs/plans/minimize-lambda-entrypoint-mjs-shell.md).
+// The "typed core, thin shell" split (docs/plans/done/minimize-lambda-entrypoint-mjs-shell.md).
 // The `.mjs` shell owns the untyped seams — reading `HANDLER_CONFIG`, the dynamic
 // `import()` of user Spec/Behavior modules, and the functor wiring that consumes
 // those runtime-loaded modules (`EventLog_Operations.Make`, `Aggregate_Callback.Make`,

package/src/adapter/Runtime/AutomationSliceEntryPoint.mjs

@@ -4,7 +4,7 @@
 // by source URN.
 //
 // Thin untyped shell ("typed core, thin shell" —
-// docs/plans/minimize-lambda-entrypoint-mjs-shell.md): this file owns ONLY the
+// docs/plans/done/minimize-lambda-entrypoint-mjs-shell.md): this file owns ONLY the
 // inherently-untyped seam — the dynamic `import()` of the spec + body modules
 // named in HANDLER_CONFIG and the curried functor applications consuming them
 // (AutomationSlice_Callback.Make(Spec)(Automation) /

package/src/adapter/Runtime/AutomationSliceEntryPoint_Ops.res

@@ -1,7 +1,7 @@
 // Typed cold-start core for the AutomationSlice / OutboundTranslationSlice
 // Lambda entry point.
 //
-// The "typed core, thin shell" split (docs/plans/minimize-lambda-entrypoint-mjs-shell.md):
+// The "typed core, thin shell" split (docs/plans/done/minimize-lambda-entrypoint-mjs-shell.md):
 // AutomationSliceEntryPoint.mjs keeps only the inherently-untyped seam — the
 // dynamic `import()` of the spec + body modules named in HANDLER_CONFIG and
 // the curried callback-functor applications consuming them

package/src/adapter/Runtime/CounterEntryPoint.mjs

@@ -4,7 +4,7 @@
 // Routes DynamoDB Stream events from references and counts tables.
 //
 // Thin untyped shell ("typed core, thin shell" —
-// docs/plans/minimize-lambda-entrypoint-mjs-shell.md): this file owns ONLY the
+// docs/plans/done/minimize-lambda-entrypoint-mjs-shell.md): this file owns ONLY the
 // seams that are inherently untyped — the dynamic `import()` of the
 // target-spec/mappings modules named in HANDLER_CONFIG, the `patchSpecId`
 // fix-up, and the MakeCounterHandler functor application consuming them.

package/src/adapter/Runtime/CounterEntryPoint_Ops.res

@@ -1,6 +1,6 @@
 // Typed cold-start core for the Counter Lambda entry point.
 //
-// The "typed core, thin shell" split (docs/plans/minimize-lambda-entrypoint-mjs-shell.md):
+// The "typed core, thin shell" split (docs/plans/done/minimize-lambda-entrypoint-mjs-shell.md):
 // CounterEntryPoint.mjs keeps only the untyped seam — the dynamic `import()`
 // of the target-spec/mappings modules named in HANDLER_CONFIG, the
 // `patchSpecId` fix-up, and the EventMapper_Callback.MakeCounterHandler