@reventlessdev/reventless-aws 3.0.0-alpha.175 → 3.0.0-alpha.177

package/src/adapter/QueryDb/PgQueryResolver_Lambda.res

@@ -0,0 +1,335 @@
+// Runtime handler for the shared Postgres GraphQL-read Lambda (B3.2).
+//
+// Postgres-backed read models have no per-table AppSync data source, so their
+// GraphQL Query fields route through one in-VPC "PgQueryResolver" Lambda
+// registered as an AppSync Lambda data source (B3.2b). Each resolver field's
+// APPSYNC_JS template invokes this Lambda with
+//   { readModelName, kind, index?, arguments, identity }
+// and this handler dispatches to the Postgres query push-downs
+// (QueryEnginePostgres) + the shared connection spec (QueryDbListQuery).
+//
+// This module is the provider-agnostic *dispatch* — the headless twin of
+// reventless-local's `QueryDbResolvers_GraphQL` (which registers graphql-yoga
+// resolvers). It returns JSON straight to AppSync instead. The per-read-model
+// context (ops set, push-downs, indexes, capability, …) is bound at Lambda init
+// by the entry point (PgQueryResolverEntryPoint.mjs, B3.2b) and registered here;
+// `dispatch` itself is pure over a `binding`, so it is unit-tested with an
+// in-memory mock (no Postgres) — the SQL correctness lives in
+// QueryEnginePostgres and is covered by its PG_URL-gated parity test.
+
+let log = ReventlessCore.Logger.fromEnv()
+
+@val external atob: string => string = "atob"
+
+// Where a cross-table resolver reads the target's sort-key value from.
+// `kind`: "field" (the parent object) | "arg" (the GraphQL arguments).
+type subIdSource = {kind: string, name: string}
+
+// Wire payload from the resolver template. `arguments` mirrors the field name the
+// other Invoke templates use (QueryInterceptor_Lambda, invokeCommandGenerator).
+// The cross-table fields (B3.2c) are present only for resolveOne/resolveMany:
+type payload = {
+  readModelName: string,
+  kind: string,
+  index?: string,
+  // Cross-table (@resolves/@resolvesMany) — see B3.2c dispatch below.
+  target?: string,
+  source?: JSON.t,
+  sourceIdField?: string,
+  sourceIdsField?: string,
+  sourceSubId?: subIdSource,
+  targetIndex?: string,
+  targetIndexIdField?: string,
+  multi?: bool,
+  arguments: JSON.t,
+  identity: Reventless.Identity.t,
+}
+
+// The Postgres query push-downs a binding needs (QueryEnginePostgres.Make
+// provides these; the mock in tests provides in-memory equivalents).
+type pushdowns = {
+  indexLookup: (~readModelName: string, string, string) => promise<array<JSON.t>>,
+  byIds: (~readModelName: string, array<string>) => promise<array<JSON.t>>,
+  listPage: (
+    ~readModelName: string,
+    ~argsDict: dict<JSON.t>,
+    ~capability: ReventlessCore.GraphQL_FragmentGenerator.serverCapability,
+    ~labelField: string,
+  ) => promise<option<JSON.t>>,
+  // Sub-id connection ({single}Items) — keyset over sub_key within a partition.
+  itemsPage: (
+    ~readModelName: string,
+    ~subIdField: string,
+    ~id: string,
+    ~argsDict: dict<JSON.t>,
+  ) => promise<JSON.t>,
+  // Full materialisation for the list fallback (shapes listPage declines).
+  scanAll: (~readModelName: string) => promise<array<JSON.t>>,
+}
+
+// Per-read-model dispatch context, bound once at Lambda init.
+type binding = {
+  ops: ReventlessCore.QueryDb_Adapter.operations,
+  pushdowns: pushdowns,
+  indexes: array<Reventless.ReadModel.indexConfig>,
+  subIdField: option<string>,
+  capability: ReventlessCore.GraphQL_FragmentGenerator.serverCapability,
+  labelField: string,
+  includeIdParam: bool,
+  authorization: Reventless.Authorization.permission,
+}
+
+// -- arg helpers -------------------------------------------------------------
+let argObj = (args: JSON.t): dict<JSON.t> =>
+  args->JSON.Decode.object->Option.getOr(Dict.make())
+let argStr = (args: JSON.t, key: string): option<string> =>
+  args->argObj->Dict.get(key)->Option.flatMap(JSON.Decode.string)
+let argStrs = (args: JSON.t, key: string): array<string> =>
+  args
+  ->argObj
+  ->Dict.get(key)
+  ->Option.flatMap(JSON.Decode.array)
+  ->Option.getOr([])
+  ->Array.filterMap(JSON.Decode.string)
+
+// Add `id` (= partition key) to an item when absent — matches the shape the
+// DynamoDB resolvers and the shared spec return.
+let withId = (item: JSON.t, id: string): JSON.t =>
+  switch item->JSON.Decode.object {
+  | Some(obj) if obj->Dict.get("id")->Option.isNone =>
+    let copy = Dict.copy(obj)
+    copy->Dict.set("id", JSON.Encode.string(id))
+    JSON.Encode.object(copy)
+  | _ => item
+  }
+
+let emptyConnection = (): JSON.t =>
+  ReventlessCore.QueryDbListQuery.buildConnection(
+    ~pageItems=[],
+    ~hasNextPage=false,
+    ~hasPreviousPage=false,
+    ~cursorValueOf=_ => "",
+  )
+
+// Spec-level authorization then the (optional) user interceptor — mirrors
+// QueryDbResolvers_GraphQL.runInterceptor. Denials return the kind's empty shape
+// (the provider-agnostic resolver behaviour), not an error.
+let runInterceptor = async (~binding, ~payload): ReventlessCore.QueryDb_Callback.interceptResult => {
+  if !Reventless.Authorization.isAllowed(binding.authorization, payload.identity) {
+    Deny("Forbidden")
+  } else {
+    switch ReventlessCore.QueryDb_Callback.queryInterceptorHook.contents {
+    | None => Allow
+    | Some(interceptor) =>
+      await interceptor(
+        ~identity=payload.identity,
+        ~readModelName=payload.readModelName,
+        ~args=payload.arguments,
+      )
+    }
+  }
+}
+
+let dispatch = async (~binding: binding, ~payload: payload): JSON.t => {
+  let rm = payload.readModelName
+  switch await runInterceptor(~binding, ~payload) {
+  | Deny(_) =>
+    // Empty shape per kind (null for single, connection for list/items, [] else).
+    let isMulti = payload.multi->Option.getOr(false)
+    switch payload.kind {
+    | "getById" => JSON.Encode.null
+    | "resolveOne" if !isMulti => JSON.Encode.null
+    | "list" | "items" => emptyConnection()
+    | _ => JSON.Encode.array([])
+    }
+  | Allow =>
+    switch payload.kind {
+    | "getById" =>
+      let id = payload.arguments->argStr("id")->Option.getOr("")
+      switch await binding.ops.load(id) {
+      | Ok(items) =>
+        switch items->Array.get(0) {
+        | Some(item) => binding.includeIdParam ? withId(item, id) : item
+        | None => JSON.Encode.null
+        }
+      | Error(_) => JSON.Encode.null
+      }
+
+    | "byIds" =>
+      let ids = payload.arguments->argStrs("ids")
+      JSON.Encode.array(await binding.pushdowns.byIds(~readModelName=rm, ids))
+
+    | "items" =>
+      // Sub-id connection: {single}Items(id, filter, first/after/last/before).
+      // Requires a subIdField; without one it's an empty connection.
+      switch binding.subIdField {
+      | Some(subIdField) =>
+        let id = payload.arguments->argStr("id")->Option.getOr("")
+        await binding.pushdowns.itemsPage(
+          ~readModelName=rm,
+          ~subIdField,
+          ~id,
+          ~argsDict=payload.arguments->argObj,
+        )
+      | None => emptyConnection()
+      }
+
+    | "index" =>
+      // The index arg name is the index; its stored field is idField ?? index.
+      let indexName = payload.index->Option.getOr("")
+      let field =
+        binding.indexes
+        ->Array.find(ic => ic.index === indexName)
+        ->Option.flatMap(ic => ic.idField)
+        ->Option.getOr(indexName)
+      let value = payload.arguments->argStr(indexName)->Option.getOr("")
+      JSON.Encode.array(await binding.pushdowns.indexLookup(~readModelName=rm, field, value))
+
+    | "list" =>
+      let argsDict = payload.arguments->argObj
+      switch await binding.pushdowns.listPage(
+        ~readModelName=rm,
+        ~argsDict,
+        ~capability=binding.capability,
+        ~labelField=binding.labelField,
+      ) {
+      | Some(conn) => conn
+      | None =>
+        // Shapes listPage declines (search/searchPrefix/ids/backward) → run the
+        // shared spec over the materialised model. No Relay global-id decoding
+        // in the Lambda, so `decodeLocalId` is a no-op (the `ids` filter still
+        // matches raw item ids).
+        let items = await binding.pushdowns.scanAll(~readModelName=rm)
+        ReventlessCore.QueryDbListQuery.run(
+          ~items,
+          ~argsDict,
+          ~capability=binding.capability,
+          ~labelField=binding.labelField,
+          ~decodeLocalId=_ => None,
+        )
+      }
+
+    // Cross-table single-ID field resolver (@resolves). `binding` is the TARGET
+    // binding (the handler looks it up by payload.target); the key comes from the
+    // parent object (payload.source[sourceIdField]).
+    | "resolveOne" =>
+      let target = payload.target->Option.getOr(rm)
+      let source = payload.source->Option.getOr(JSON.Encode.null)
+      let key = source->argStr(payload.sourceIdField->Option.getOr(""))->Option.getOr("")
+      let items = switch payload.targetIndex {
+      | Some(ix) =>
+        await binding.pushdowns.indexLookup(
+          ~readModelName=target,
+          payload.targetIndexIdField->Option.getOr(ix),
+          key,
+        )
+      | None =>
+        switch await binding.ops.load(key) {
+        | Ok(items) => items
+        | Error(_) => []
+        }
+      }
+      // Optional target sort-key filter (source field or GraphQL arg).
+      let filtered = switch (payload.sourceSubId, binding.subIdField) {
+      | (Some({kind, name}), Some(subField)) =>
+        let subVal =
+          switch kind {
+          | "arg" => payload.arguments->argStr(name)
+          | _ => source->argStr(name)
+          }->Option.getOr("")
+        items->Array.filter(it => it->argStr(subField)->Option.getOr("") == subVal)
+      | _ => items
+      }
+      if payload.multi->Option.getOr(false) {
+        JSON.Encode.array(filtered)
+      } else {
+        switch filtered->Array.get(0) {
+        | Some(item) => item
+        | None => JSON.Encode.null
+        }
+      }
+
+    // Cross-table batch field resolver (@resolvesMany). ids come from the parent
+    // object (payload.source[sourceIdsField]); BatchGet the target by partition
+    // key (missing ids drop out).
+    | "resolveMany" =>
+      let target = payload.target->Option.getOr(rm)
+      let source = payload.source->Option.getOr(JSON.Encode.null)
+      let ids = source->argStrs(payload.sourceIdsField->Option.getOr(""))
+      JSON.Encode.array(await binding.pushdowns.byIds(~readModelName=target, ids))
+
+    | other =>
+      // Fail loudly on unmapped kinds (feature-parity guard, per the B3.2 plan).
+      log.error(~comp="PgQueryResolver_Lambda", `unmapped resolver kind '${other}' for ${rm}`)
+      JsError.throwWithMessage(`PgQueryResolver: unmapped resolver kind '${other}' for ${rm}`)
+    }
+  }
+}
+
+// Per-read-model binding registry, populated by the entry point at Lambda init.
+let bindings: dict<binding> = Dict.make()
+let register = (~readModelName: string, binding: binding): unit =>
+  bindings->Dict.set(readModelName, binding)
+
+// Relay node type → read-model-name map (B3.2c), populated at Lambda init from
+// the deploy-time registerNodeType calls.
+let nodeTypeMap: dict<string> = Dict.make()
+let registerNodeType = (~typeName: string, ~readModelName: string): unit =>
+  nodeTypeMap->Dict.set(typeName, readModelName)
+
+// node(id: ID!) — decode the global id (base64 of `typeName:localId`, matching
+// AppSync's nodeDecodeGlobalId), map typeName → read model, load by localId,
+// return the item tagged with __typename and the original global id. Runs the
+// target's authorization/interceptor. Self-contained (getById returns raw ids,
+// so no encoding elsewhere is affected).
+let handleNode = async (~payload: payload): JSON.t => {
+  let globalId = payload.arguments->argStr("id")->Option.getOr("")
+  let decoded = try atob(globalId) catch {
+  | _ => ""
+  }
+  let colonIdx = decoded->String.indexOf(":")
+  if colonIdx <= 0 {
+    JSON.Encode.null
+  } else {
+    let typeName = decoded->String.slice(~start=0, ~end=colonIdx)
+    let localId = decoded->String.slice(~start=colonIdx + 1, ~end=decoded->String.length)
+    switch nodeTypeMap->Dict.get(typeName)->Option.flatMap(rm => bindings->Dict.get(rm)) {
+    | Some(binding) =>
+      switch await runInterceptor(~binding, ~payload) {
+      | Deny(_) => JSON.Encode.null
+      | Allow =>
+        switch await binding.ops.load(localId) {
+        | Ok(items) =>
+          switch items->Array.get(0) {
+          | Some(item) =>
+            let obj = item->JSON.Decode.object->Option.getOr(Dict.make())->Dict.copy
+            obj->Dict.set("__typename", JSON.Encode.string(typeName))
+            obj->Dict.set("id", JSON.Encode.string(globalId))
+            JSON.Encode.object(obj)
+          | None => JSON.Encode.null
+          }
+        | Error(_) => JSON.Encode.null
+        }
+      }
+    | None => JSON.Encode.null
+    }
+  }
+}
+
+let handler = async (payload: payload, _context) => {
+  // node decodes its own target; the cross-table field resolvers dispatch against
+  // the TARGET binding; everything else against the payload's own read model.
+  let bindingKey = switch payload.kind {
+  | "resolveOne" | "resolveMany" => payload.target->Option.getOr(payload.readModelName)
+  | _ => payload.readModelName
+  }
+  switch payload.kind {
+  | "node" => await handleNode(~payload)
+  | _ =>
+    switch bindings->Dict.get(bindingKey) {
+    | Some(binding) => await dispatch(~binding, ~payload)
+    | None =>
+      JsError.throwWithMessage("PgQueryResolver: no binding registered for read model " ++ bindingKey)
+    }
+  }
+}

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

@@ -0,0 +1,252 @@
+// Generated by ReScript, PLEASE EDIT WITH CARE
+
+import * as Stdlib_JSON from "@rescript/runtime/lib/es6/Stdlib_JSON.js";
+import * as Stdlib_Array from "@rescript/runtime/lib/es6/Stdlib_Array.js";
+import * as Stdlib_Option from "@rescript/runtime/lib/es6/Stdlib_Option.js";
+import * as Stdlib_JsError from "@rescript/runtime/lib/es6/Stdlib_JsError.js";
+import * as Logger$ReventlessCore from "@reventlessdev/reventless-core/src/util/Logger.res.mjs";
+import * as Authorization$Reventless from "@reventlessdev/reventless-spec/src/types/Authorization.res.mjs";
+import * as QueryDbListQuery$ReventlessCore from "@reventlessdev/reventless-core/src/components/Api/QueryDbListQuery.res.mjs";
+import * as QueryDb_Callback$ReventlessCore from "@reventlessdev/reventless-core/src/components/QueryDb/QueryDb_Callback.res.mjs";
+
+let log = Logger$ReventlessCore.fromEnv();
+
+function argObj(args) {
+  return Stdlib_Option.getOr(Stdlib_JSON.Decode.object(args), {});
+}
+
+function argStr(args, key) {
+  return Stdlib_Option.flatMap(argObj(args)[key], Stdlib_JSON.Decode.string);
+}
+
+function argStrs(args, key) {
+  return Stdlib_Array.filterMap(Stdlib_Option.getOr(Stdlib_Option.flatMap(argObj(args)[key], Stdlib_JSON.Decode.array), []), Stdlib_JSON.Decode.string);
+}
+
+function withId(item, id) {
+  let obj = Stdlib_JSON.Decode.object(item);
+  if (obj === undefined) {
+    return item;
+  }
+  if (!Stdlib_Option.isNone(obj["id"])) {
+    return item;
+  }
+  let copy = Object.assign({}, obj);
+  copy["id"] = id;
+  return copy;
+}
+
+function emptyConnection() {
+  return QueryDbListQuery$ReventlessCore.buildConnection([], false, false, param => "");
+}
+
+async function runInterceptor(binding, payload) {
+  if (!Authorization$Reventless.isAllowed(binding.authorization, payload.identity)) {
+    return {
+      TAG: "Deny",
+      _0: "Forbidden"
+    };
+  }
+  let interceptor = QueryDb_Callback$ReventlessCore.queryInterceptorHook.contents;
+  if (interceptor !== undefined) {
+    return await interceptor(payload.identity, payload.readModelName, payload.arguments);
+  } else {
+    return "Allow";
+  }
+}
+
+async function dispatch(binding, payload) {
+  let rm = payload.readModelName;
+  let match = await runInterceptor(binding, payload);
+  if (typeof match !== "object") {
+    let other = payload.kind;
+    switch (other) {
+      case "byIds" :
+        let ids = argStrs(payload.arguments, "ids");
+        return await binding.pushdowns.byIds(rm, ids);
+      case "getById" :
+        let id = Stdlib_Option.getOr(argStr(payload.arguments, "id"), "");
+        let items = await binding.ops.load(id);
+        if (items.TAG !== "Ok") {
+          return null;
+        }
+        let item = items._0[0];
+        if (item !== undefined) {
+          if (binding.includeIdParam) {
+            return withId(item, id);
+          } else {
+            return item;
+          }
+        } else {
+          return null;
+        }
+      case "index" :
+        let indexName = Stdlib_Option.getOr(payload.index, "");
+        let field = Stdlib_Option.getOr(Stdlib_Option.flatMap(binding.indexes.find(ic => ic.index === indexName), ic => ic.idField), indexName);
+        let value = Stdlib_Option.getOr(argStr(payload.arguments, indexName), "");
+        return await binding.pushdowns.indexLookup(rm, field, value);
+      case "items" :
+        let subIdField = binding.subIdField;
+        if (subIdField === undefined) {
+          return emptyConnection();
+        }
+        let id$1 = Stdlib_Option.getOr(argStr(payload.arguments, "id"), "");
+        return await binding.pushdowns.itemsPage(rm, subIdField, id$1, argObj(payload.arguments));
+      case "list" :
+        let argsDict = argObj(payload.arguments);
+        let conn = await binding.pushdowns.listPage(rm, argsDict, binding.capability, binding.labelField);
+        if (conn !== undefined) {
+          return conn;
+        }
+        let items$1 = await binding.pushdowns.scanAll(rm);
+        return QueryDbListQuery$ReventlessCore.run(items$1, argsDict, binding.capability, binding.labelField, param => {});
+      case "resolveMany" :
+        let target = Stdlib_Option.getOr(payload.target, rm);
+        let source = Stdlib_Option.getOr(payload.source, null);
+        let ids$1 = argStrs(source, Stdlib_Option.getOr(payload.sourceIdsField, ""));
+        return await binding.pushdowns.byIds(target, ids$1);
+      case "resolveOne" :
+        let target$1 = Stdlib_Option.getOr(payload.target, rm);
+        let source$1 = Stdlib_Option.getOr(payload.source, null);
+        let key = Stdlib_Option.getOr(argStr(source$1, Stdlib_Option.getOr(payload.sourceIdField, "")), "");
+        let ix = payload.targetIndex;
+        let items$2;
+        if (ix !== undefined) {
+          items$2 = await binding.pushdowns.indexLookup(target$1, Stdlib_Option.getOr(payload.targetIndexIdField, ix), key);
+        } else {
+          let items$3 = await binding.ops.load(key);
+          items$2 = items$3.TAG === "Ok" ? items$3._0 : [];
+        }
+        let match$1 = payload.sourceSubId;
+        let match$2 = binding.subIdField;
+        let filtered;
+        if (match$1 !== undefined && match$2 !== undefined) {
+          let name = match$1.name;
+          let tmp = match$1.kind === "arg" ? argStr(payload.arguments, name) : argStr(source$1, name);
+          let subVal = Stdlib_Option.getOr(tmp, "");
+          filtered = items$2.filter(it => Stdlib_Option.getOr(argStr(it, match$2), "") === subVal);
+        } else {
+          filtered = items$2;
+        }
+        if (Stdlib_Option.getOr(payload.multi, false)) {
+          return filtered;
+        }
+        let item$1 = filtered[0];
+        if (item$1 !== undefined) {
+          return item$1;
+        } else {
+          return null;
+        }
+      default:
+        log.error("PgQueryResolver_Lambda", undefined, `unmapped resolver kind '` + other + `' for ` + rm);
+        return Stdlib_JsError.throwWithMessage(`PgQueryResolver: unmapped resolver kind '` + other + `' for ` + rm);
+    }
+  } else {
+    let isMulti = Stdlib_Option.getOr(payload.multi, false);
+    let match$3 = payload.kind;
+    switch (match$3) {
+      case "getById" :
+        return null;
+      case "items" :
+      case "list" :
+        return emptyConnection();
+      case "resolveOne" :
+        if (isMulti) {
+          return [];
+        } else {
+          return null;
+        }
+      default:
+        return [];
+    }
+  }
+}
+
+let bindings = {};
+
+function register(readModelName, binding) {
+  bindings[readModelName] = binding;
+}
+
+let nodeTypeMap = {};
+
+function registerNodeType(typeName, readModelName) {
+  nodeTypeMap[typeName] = readModelName;
+}
+
+async function handleNode(payload) {
+  let globalId = Stdlib_Option.getOr(argStr(payload.arguments, "id"), "");
+  let decoded;
+  try {
+    decoded = atob(globalId);
+  } catch (exn) {
+    decoded = "";
+  }
+  let colonIdx = decoded.indexOf(":");
+  if (colonIdx <= 0) {
+    return null;
+  }
+  let typeName = decoded.slice(0, colonIdx);
+  let localId = decoded.slice(colonIdx + 1 | 0, decoded.length);
+  let binding = Stdlib_Option.flatMap(nodeTypeMap[typeName], rm => bindings[rm]);
+  if (binding === undefined) {
+    return null;
+  }
+  let match = await runInterceptor(binding, payload);
+  if (typeof match === "object") {
+    return null;
+  }
+  let items = await binding.ops.load(localId);
+  if (items.TAG !== "Ok") {
+    return null;
+  }
+  let item = items._0[0];
+  if (item === undefined) {
+    return null;
+  }
+  let obj = Object.assign({}, Stdlib_Option.getOr(Stdlib_JSON.Decode.object(item), {}));
+  obj["__typename"] = typeName;
+  obj["id"] = globalId;
+  return obj;
+}
+
+async function handler(payload, _context) {
+  let match = payload.kind;
+  let bindingKey;
+  switch (match) {
+    case "resolveMany" :
+    case "resolveOne" :
+      bindingKey = Stdlib_Option.getOr(payload.target, payload.readModelName);
+      break;
+    default:
+      bindingKey = payload.readModelName;
+  }
+  let match$1 = payload.kind;
+  if (match$1 === "node") {
+    return await handleNode(payload);
+  }
+  let binding = bindings[bindingKey];
+  if (binding !== undefined) {
+    return await dispatch(binding, payload);
+  } else {
+    return Stdlib_JsError.throwWithMessage("PgQueryResolver: no binding registered for read model " + bindingKey);
+  }
+}
+
+export {
+  log,
+  argObj,
+  argStr,
+  argStrs,
+  withId,
+  emptyConnection,
+  runInterceptor,
+  dispatch,
+  bindings,
+  register,
+  nodeTypeMap,
+  registerNodeType,
+  handleNode,
+  handler,
+}
+/* log Not a pure module */

package/src/adapter/QueryDb/QueryDbBackend.res

@@ -0,0 +1,52 @@
+// AWS-side selection for the QueryDb (read model) storage backend — the QueryDb
+// analogue of `EventLogBackend` / `DcbBackend` (B3.1,
+// docs/plans/aws-postgres-querydb-adapter.md).
+//
+// When `Platform.MakeWithConfig` is given a `~pgConnection`, it records the
+// resolved selection here BEFORE any admin/plugin `construct` runs. Read by:
+//   - `QueryDbStorage.Selectable(Stream)` — route app read-model storage to
+//     Postgres (no DynamoDB table) and bind the Postgres operation set;
+//   - `QueryDbResolvers.Selectable` — suppress AppSync resolvers for
+//     Postgres-backed read models (GraphQL reads land with B3.2's Lambda data
+//     source; until then those fields are unresolved);
+//   - the ReadModel/StateViewSlice runtime builders — inject `pgConnection` into
+//     Postgres-backed handlers' HANDLER_CONFIG entries and put the projection
+//     Lambdas in-VPC with secret access.
+//
+// ADMIN EXEMPTION: platform/admin read models (Plugins, UIFragmentRegistry, …)
+// stay on DynamoDB even when Postgres is selected. Deploy-time consumers (the
+// AppSync schema-clobber guard's Plugin-RM scan, `PLUGIN_RM_TABLE_NAME` gates,
+// retire hooks) query these tables during `pulumi up` — from outside the VPC —
+// and the whole platform lifecycle depends on them. The platform registers the
+// exempt names before Admin.construct.
+
+type selection = {
+  connectionConfig: Pulumi.Output.t<PgConnection.connectionConfig>,
+  /** DB-access security group every projection Lambda attaches (PgConnection.securityGroupId). */
+  securityGroupId: Pulumi.Output.t<string>,
+  /** Private subnets for the in-VPC projection Lambdas (PgConnection.subnetIds). */
+  subnetIds: array<Pulumi.Input.t<string>>,
+}
+
+let selectionRef: ref<option<selection>> = ref(None)
+
+/** Record the QueryDb Postgres selection. Called once by the platform before construct. */
+let set = (sel: selection) => selectionRef := Some(sel)
+
+/** The active QueryDb Postgres selection, if the platform was given a `PgConnection`. */
+let get = (): option<selection> => selectionRef.contents
+
+// Read-model names that stay on DynamoDB regardless of the selection.
+let exemptNames: array<string> = []
+
+/** Exempt an (admin) read model from the Postgres selection. Called by the
+    platform for every admin read model before Admin.construct. */
+let exempt = (name: string) => exemptNames->Array.push(name)->ignore
+
+/** Whether this read model's QueryDb is Postgres-backed on this platform. */
+let isPostgresFor = (name: string): bool =>
+  selectionRef.contents->Option.isSome && !(exemptNames->Array.includes(name))
+
+/** Whether ANY read model on this platform is Postgres-backed (used to decide
+    whether the projection Lambdas need VPC/secret access). */
+let isPostgres = (): bool => selectionRef.contents->Option.isSome

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

@@ -0,0 +1,44 @@
+// Generated by ReScript, PLEASE EDIT WITH CARE
+
+import * as Stdlib_Option from "@rescript/runtime/lib/es6/Stdlib_Option.js";
+
+let selectionRef = {
+  contents: undefined
+};
+
+function set(sel) {
+  selectionRef.contents = sel;
+}
+
+function get() {
+  return selectionRef.contents;
+}
+
+let exemptNames = [];
+
+function exempt(name) {
+  exemptNames.push(name);
+}
+
+function isPostgresFor(name) {
+  if (Stdlib_Option.isSome(selectionRef.contents)) {
+    return !exemptNames.includes(name);
+  } else {
+    return false;
+  }
+}
+
+function isPostgres() {
+  return Stdlib_Option.isSome(selectionRef.contents);
+}
+
+export {
+  selectionRef,
+  set,
+  get,
+  exemptNames,
+  exempt,
+  isPostgresFor,
+  isPostgres,
+}
+/* No side effect */