@reventlessdev/reventless-aws 3.0.0-alpha.231 → 3.0.0-alpha.233

package/src/adapter/Runtime/ExtensionPointEntryPoint_Ops.res.mjs

@@ -0,0 +1,111 @@
+// Generated by ReScript, PLEASE EDIT WITH CARE
+
+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 HandlerFactoryHelpersMjs from "./HandlerFactoryHelpers.mjs";
+import * as CommandTopicChannel_SQS_Runtime$ReventlessAws from "../CommandTopic/CommandTopicChannel_SQS_Runtime.res.mjs";
+
+function setRequestId(prim) {
+  HandlerFactoryHelpersMjs.setRequestId(prim);
+}
+
+function runEffect(prim0, prim1) {
+  return HandlerFactoryHelpersMjs.runEffect(prim0, prim1);
+}
+
+function extractMetaField(prim0, prim1) {
+  return HandlerFactoryHelpersMjs.extractMetaField(prim0, prim1);
+}
+
+function extractSentTimestamp(prim) {
+  return HandlerFactoryHelpersMjs.extractSentTimestamp(prim);
+}
+
+function extractRetryCount(prim) {
+  return HandlerFactoryHelpersMjs.extractRetryCount(prim);
+}
+
+function logDebug(prim0, prim1) {
+  HandlerFactoryHelpersMjs.log.debug(prim0, prim1);
+}
+
+function parseHandlerConfig(raw) {
+  return JSON.parse(raw);
+}
+
+function makeCallbackSpec(config) {
+  return {
+    publishToAggregates: Object.fromEntries(Object.entries(Stdlib_Option.getOr(config.publishToAggregates, {})).map(param => {
+      let queueUrl = Stdlib_Option.getOr(process.env[param[1]], "");
+      let queue = {
+        id: queueUrl,
+        name: queueUrl,
+        arn: ""
+      };
+      return [
+        param[0],
+        CommandTopicChannel_SQS_Runtime$ReventlessAws.publishJsons(queue, "SQS_FIFO")
+      ];
+    })),
+    commandTopicResources: [],
+    scheduler: {
+      createSchedule: (param, param$1) => Stdlib_JsError.throwWithMessage("Scheduler not available in bundled ExtensionPoint handler"),
+      deleteSchedule: (param, param$1) => Stdlib_JsError.throwWithMessage("Scheduler not available in bundled ExtensionPoint handler")
+    },
+    queryEngine: {
+      scan: (param, param$1, param$2) => Stdlib_JsError.throwWithMessage("QueryEngine not available in bundled ExtensionPoint handler"),
+      query: (param, param$1, param$2, param$3, param$4, param$5, param$6) => Stdlib_JsError.throwWithMessage("QueryEngine not available in bundled ExtensionPoint handler")
+    },
+    resourceNaming: {
+      validateName: n => n,
+      urnName: n => n
+    }
+  };
+}
+
+function makeBuilt(config, specName, handleJsonCommands) {
+  let queueUrl = Stdlib_Option.getOr(config.queueUrl, "");
+  let queue = {
+    id: queueUrl,
+    name: queueUrl,
+    arn: ""
+  };
+  return {
+    comp: `ExtensionPoint(` + specName + `)`,
+    sqsHandler: CommandTopicChannel_SQS_Runtime$ReventlessAws.handleQueueEvent(queue, handleJsonCommands)
+  };
+}
+
+function makeHandler(buildPromise) {
+  return async (event, context) => {
+    HandlerFactoryHelpersMjs.setRequestId(context.awsRequestId);
+    let match = await buildPromise;
+    let records = event.Records;
+    let prim0 = `processing ` + records.length.toString() + ` record(s)`;
+    HandlerFactoryHelpersMjs.log.debug(prim0, {
+      comp: "ExtensionPointRuntime"
+    });
+    await HandlerFactoryHelpersMjs.runEffect(match.sqsHandler(event, context), {
+      correlationId: HandlerFactoryHelpersMjs.extractMetaField(records, "correlationId"),
+      causationId: HandlerFactoryHelpersMjs.extractMetaField(records, "causationId"),
+      comp: match.comp,
+      timestamp: HandlerFactoryHelpersMjs.extractSentTimestamp(records),
+      retryCount: HandlerFactoryHelpersMjs.extractRetryCount(records)
+    });
+    return "";
+  };
+}
+
+export {
+  setRequestId,
+  runEffect,
+  extractMetaField,
+  extractSentTimestamp,
+  extractRetryCount,
+  logDebug,
+  parseHandlerConfig,
+  makeCallbackSpec,
+  makeBuilt,
+  makeHandler,
+}
+/* ./HandlerFactoryHelpers.mjs Not a pure module */

package/src/adapter/Runtime/PgChangeFeedRelayEntryPoint.res

@@ -0,0 +1,96 @@
+// PgChangeFeedRelay Lambda entry point (scheduled poll — B2.3) — compiled,
+// type-checked ReScript (replaces the hand-written PgChangeFeedRelayEntryPoint.mjs
+// shell; no dynamic user-module import, so no untyped seam is needed).
+//
+// Triggered on a schedule (EventBridge rate rule). Each invocation drains every
+// Postgres log listed in HANDLER_CONFIG from its checkpoint — DCB (`dcb_event`)
+// and classic aggregate (`event_log`) logs alike — and relays the events,
+// transformed into the {id, meta, event} shape, onto the plugin EventCollector
+// SQS queue — which then fans out to projections, aggregate command topics, and
+// the cross-plugin SNS EventTopic.
+// See docs/plans/done/aws-postgres-change-feed-bridge.md.
+//
+// Runtime-pure: `PgConnection.connectionConfig` is referenced as a type only
+// (erased — no runtime import of the Pulumi-carrying PgConnection module);
+// PgChangeFeedRelay_Runtime/Util_SQS_Runtime are runtime modules. Deploy-time
+// wiring lives in PgChangeFeedRelay_Builder.
+//
+// HANDLER_CONFIG shape:
+//   { "logs": [ { "pgConnection": {host,port,database,username,secretArn},
+//                 "logName": string,          // dcb_event/event_log log_name
+//                 "subscriber": string,        // per-log checkpoint key
+//                 "targetQueueUrl": string,    // plugin EventCollector SQS URL
+//                 "kind"?: "classic",          // absent → DCB
+//                 "partitionTag"?: <derivedPartitionTag> } ] }  // DCB only
+
+@val @scope("process") external processEnv: dict<string> = "env"
+
+// Structured JSON logging shared by every deployed entry point (HandlerFactoryHelpers).
+type logExtra = {comp?: string}
+@module("./HandlerFactoryHelpers.mjs") @scope("log")
+external logDebug: (string, logExtra) => unit = "debug"
+@module("./HandlerFactoryHelpers.mjs") @scope("log")
+external logWarn: (string, logExtra) => unit = "warn"
+
+type relayLogConfig = {
+  pgConnection: PgConnection.connectionConfig,
+  logName: string,
+  subscriber: string,
+  targetQueueUrl: string,
+  // Absent → DCB (`dcb_event`); "classic" → aggregate `event_log`.
+  kind?: string,
+  // DCB only: the sury-encoded derived partition tag (parsed inside relayWithPool).
+  partitionTag?: JSON.t,
+}
+type handlerConfig = {logs?: array<relayLogConfig>}
+@val @scope("JSON") external parseHandlerConfig: string => handlerConfig = "parse"
+
+// Standard (non-FIFO) EventCollector queue — no message group id needed. The
+// SQS handler parses each body straight back to JSON (Util_SQS_Runtime.parseSqsRecord).
+let makeSendBatch = (targetQueueUrl: string): (array<JSON.t> => promise<unit>) => {
+  let queue: Util_SQS_Runtime.resolvedQueue = {id: targetQueueUrl, name: targetQueueUrl, arn: ""}
+  jsons =>
+    jsons
+    ->Array.map(json => Util_SQS_Runtime.sendMessage(queue, json->JSON.stringify))
+    ->Promise.all
+    ->Promise.thenResolve(_ => ())
+}
+
+// Drain one log and relay it. Log-and-continue on failure — a failed log this
+// tick is retried next tick from its unchanged checkpoint (at-least-once;
+// projections are idempotent).
+let relayLog = async (l: relayLogConfig): unit => {
+  let sendBatch = makeSendBatch(l.targetQueueUrl)
+  try {
+    let count = switch l.kind {
+    | Some("classic") =>
+      await PgChangeFeedRelay_Runtime.relayClassic(
+        ~config=l.pgConnection,
+        ~logName=l.logName,
+        ~subscriber=l.subscriber,
+        ~sendBatch,
+      )
+    | _ =>
+      await PgChangeFeedRelay_Runtime.relay(
+        ~config=l.pgConnection,
+        ~logName=l.logName,
+        ~subscriber=l.subscriber,
+        ~partitionTagJson=?l.partitionTag,
+        ~sendBatch,
+      )
+    }
+    logDebug(`relayed ${count->Int.toString} event(s) for ${l.logName}`, {comp: "PgChangeFeedRelay"})
+  } catch {
+  | exn =>
+    let msg = exn->JsExn.fromException->Option.flatMap(JsExn.message)->Option.getOr("unknown error")
+    logWarn(`relay failed for ${l.logName}: ${msg}`, {comp: "PgChangeFeedRelay"})
+  }
+}
+
+let handler = async (_event: JSON.t, _context: PulumiAws.Lambda.context) => {
+  let config =
+    processEnv->Dict.get("HANDLER_CONFIG")->Option.getOr(`{"logs":[]}`)->parseHandlerConfig
+  let logs = config.logs->Option.getOr([])
+  let _ = await logs->Array.map(relayLog)->Promise.all
+  ""
+}

package/src/adapter/Runtime/PgChangeFeedRelayEntryPoint.res.mjs

@@ -0,0 +1,70 @@
+// Generated by ReScript, PLEASE EDIT WITH CARE
+
+import * as Stdlib_JsExn from "@rescript/runtime/lib/es6/Stdlib_JsExn.js";
+import * as Stdlib_Option from "@rescript/runtime/lib/es6/Stdlib_Option.js";
+import * as Primitive_exceptions from "@rescript/runtime/lib/es6/Primitive_exceptions.js";
+import * as HandlerFactoryHelpersMjs from "./HandlerFactoryHelpers.mjs";
+import * as Util_SQS_Runtime$ReventlessAws from "../../util/Util_SQS_Runtime.res.mjs";
+import * as PgChangeFeedRelay_Runtime$ReventlessAws from "../Postgres/PgChangeFeedRelay_Runtime.res.mjs";
+
+function logDebug(prim0, prim1) {
+  HandlerFactoryHelpersMjs.log.debug(prim0, prim1);
+}
+
+function logWarn(prim0, prim1) {
+  HandlerFactoryHelpersMjs.log.warn(prim0, prim1);
+}
+
+function makeSendBatch(targetQueueUrl) {
+  let queue = {
+    id: targetQueueUrl,
+    name: targetQueueUrl,
+    arn: ""
+  };
+  return jsons => Promise.all(jsons.map(json => Util_SQS_Runtime$ReventlessAws.sendMessage(queue, undefined, JSON.stringify(json)))).then(param => {});
+}
+
+async function relayLog(l) {
+  let sendBatch = makeSendBatch(l.targetQueueUrl);
+  try {
+    let match = l.kind;
+    let count;
+    let exit = 0;
+    if (match === "classic") {
+      count = await PgChangeFeedRelay_Runtime$ReventlessAws.relayClassic(l.pgConnection, l.logName, l.subscriber, sendBatch);
+    } else {
+      exit = 1;
+    }
+    if (exit === 1) {
+      count = await PgChangeFeedRelay_Runtime$ReventlessAws.relay(l.pgConnection, l.logName, l.subscriber, l.partitionTag, sendBatch);
+    }
+    let prim0 = `relayed ` + count.toString() + ` event(s) for ` + l.logName;
+    HandlerFactoryHelpersMjs.log.debug(prim0, {
+      comp: "PgChangeFeedRelay"
+    });
+    return;
+  } catch (raw_exn) {
+    let exn = Primitive_exceptions.internalToException(raw_exn);
+    let msg = Stdlib_Option.getOr(Stdlib_Option.flatMap(Stdlib_JsExn.fromException(exn), Stdlib_JsExn.message), "unknown error");
+    HandlerFactoryHelpersMjs.log.warn(`relay failed for ` + l.logName + `: ` + msg, {
+      comp: "PgChangeFeedRelay"
+    });
+    return;
+  }
+}
+
+async function handler(_event, _context) {
+  let config = JSON.parse(Stdlib_Option.getOr(process.env["HANDLER_CONFIG"], `{"logs":[]}`));
+  let logs = Stdlib_Option.getOr(config.logs, []);
+  await Promise.all(logs.map(relayLog));
+  return "";
+}
+
+export {
+  logDebug,
+  logWarn,
+  makeSendBatch,
+  relayLog,
+  handler,
+}
+/* Stdlib_JsExn Not a pure module */

package/src/adapter/Runtime/PgMigrationEntryPoint.res

@@ -0,0 +1,54 @@
+// One-shot Postgres schema-migration Lambda entry point (A3) — compiled,
+// type-checked ReScript (replaces the hand-written PgMigrationEntryPoint.mjs
+// shell; no dynamic user-module import, so no untyped seam is needed).
+//
+// Invoked once during `pulumi up` by an `aws.lambda.Invocation` resource, from
+// INSIDE the DB's VPC, so the deploy runner needs no network path to a private
+// RDS instance. Runs the exact idempotent `PgSchema.ensureSchema` the local
+// backend runs at startup (reventless-local's `postgres` smart constructor), so
+// the AWS schema is byte-identical to local — zero drift. Every statement is
+// `IF NOT EXISTS`, so re-invocation (e.g. after a schema-DDL change bumps the
+// Lambda layer) is safe.
+//
+// Runtime-pure: `PgConnection.connectionConfig` is referenced as a type only
+// (erased — no runtime import of the Pulumi-carrying PgConnection module);
+// PgRuntime/PgSchema are runtime modules. Deploy-time wiring lives in
+// PgMigration_Builder.
+//
+// HANDLER_CONFIG shape:
+//   { "pgConnection": { host, port, database, username, secretArn } }
+
+@val @scope("process") external processEnv: dict<string> = "env"
+
+// Structured JSON logging shared by every deployed entry point (HandlerFactoryHelpers).
+type logExtra = {comp?: string}
+@module("./HandlerFactoryHelpers.mjs") @scope("log")
+external logInfo: (string, logExtra) => unit = "info"
+
+type handlerConfig = {pgConnection?: PgConnection.connectionConfig}
+@val @scope("JSON") external parseHandlerConfig: string => handlerConfig = "parse"
+
+// Config parse → pool → ensureSchema, with the pool source injectable so the
+// orchestration is integration-testable against a real Postgres without the
+// Secrets Manager round-trip (mirrors PgChangeFeedRelay_Runtime's
+// relayWithPool/relay split). `~makePool` defaults to the production `poolFor`,
+// which memoises one pool per secret ARN per container and resolves the
+// RDS-managed password from Secrets Manager via a cached provider.
+let runMigration = async (
+  config: handlerConfig,
+  ~makePool: PgConnection.connectionConfig => ReventlessPostgres.PgDriver.pool=PgRuntime.poolFor,
+): string => {
+  switch config.pgConnection {
+  | None => JsError.throwWithMessage("PgMigrationEntryPoint: HANDLER_CONFIG has no pgConnection")
+  | Some(conn) =>
+    let pool = makePool(conn)
+    await ReventlessPostgres.PgSchema.ensureSchema(pool)
+    logInfo(`ensureSchema completed for ${conn.database}`, {comp: "PgMigration"})
+    "ok"
+  }
+}
+
+let handler = async (_event: JSON.t, _context: PulumiAws.Lambda.context) => {
+  let config = processEnv->Dict.get("HANDLER_CONFIG")->Option.getOr("{}")->parseHandlerConfig
+  await runMigration(config)
+}

package/src/adapter/Runtime/PgMigrationEntryPoint.res.mjs

@@ -0,0 +1,37 @@
+// Generated by ReScript, PLEASE EDIT WITH CARE
+
+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 PgRuntime$ReventlessAws from "../Postgres/PgRuntime.res.mjs";
+import * as HandlerFactoryHelpersMjs from "./HandlerFactoryHelpers.mjs";
+import * as PgSchema$ReventlessPostgres from "@reventlessdev/reventless-postgres/src/PgSchema.res.mjs";
+
+function logInfo(prim0, prim1) {
+  HandlerFactoryHelpersMjs.log.info(prim0, prim1);
+}
+
+async function runMigration(config, makePoolOpt) {
+  let makePool = makePoolOpt !== undefined ? makePoolOpt : PgRuntime$ReventlessAws.poolFor;
+  let conn = config.pgConnection;
+  if (conn === undefined) {
+    return Stdlib_JsError.throwWithMessage("PgMigrationEntryPoint: HANDLER_CONFIG has no pgConnection");
+  }
+  let pool = makePool(conn);
+  await PgSchema$ReventlessPostgres.ensureSchema(pool);
+  HandlerFactoryHelpersMjs.log.info(`ensureSchema completed for ` + conn.database, {
+    comp: "PgMigration"
+  });
+  return "ok";
+}
+
+async function handler(_event, _context) {
+  let config = JSON.parse(Stdlib_Option.getOr(process.env["HANDLER_CONFIG"], "{}"));
+  return await runMigration(config, undefined);
+}
+
+export {
+  logInfo,
+  runMigration,
+  handler,
+}
+/* PgRuntime-ReventlessAws Not a pure module */

package/src/adapter/Runtime/PgQueryResolverEntryPoint.mjs

@@ -4,78 +4,43 @@
 // fields (they have no per-table AppSync data source). At cold start it reads
 // QUERY_RESOLVER_CONFIG (one shared pgConnection + one handler per read model),
 // dynamically imports each spec package, and registers a per-read-model
-// `binding` (ops + QueryEnginePostgres push-downs + indexes/subIdField/capability
-// + baked labelField/includeIdParam + authorization) into
-// PgQueryResolver_Lambda. AppSync invokes `handler` with the resolver payload
-// { readModelName, kind, index?, arguments, identity }, which
+// `binding` into PgQueryResolver_Lambda. AppSync invokes `handler` with the
+// resolver payload { readModelName, kind, index?, arguments, identity }, which
 // PgQueryResolver_Lambda.dispatch routes.
 //
-// ReScript labeled args compile positionally, so the engine push-downs
-// (indexLookup/byIds/listPage/scan) are assigned straight into the `pushdowns`
-// record — same calling convention PgQueryResolver_Lambda.dispatch invokes them
-// with (verified against the compiled QueryEnginePostgres output).
-
-import { poolFor } from "@reventlessdev/reventless-aws/src/adapter/Postgres/PgRuntime.res.mjs";
-import { Make as makeEngine } from "@reventlessdev/reventless-postgres/src/QueryEnginePostgres.res.mjs";
-import { opsFor as pgQdbOpsFor } from "@reventlessdev/reventless-aws/src/adapter/QueryDb/QueryDbStorage_Postgres_Runtime.res.mjs";
-import { deriveServerCapability } from "@reventlessdev/reventless-core/src/components/Api/GraphQL_FragmentGenerator.res.mjs";
-import { register, registerNodeType, handler as dispatchHandler } from "@reventlessdev/reventless-aws/src/adapter/QueryDb/PgQueryResolver_Lambda.res.mjs";
+// Thin untyped shell ("typed core, thin shell" —
+// docs/plans/minimize-lambda-entrypoint-mjs-shell.md): this file owns ONLY the
+// seams that are inherently untyped — the dynamic `import()` of the spec
+// packages named in QUERY_RESOLVER_CONFIG, the `patchSpecId` fix-up, and the
+// reads of the runtime-loaded modules' exports. QUERY_RESOLVER_CONFIG parsing,
+// the pool/engine construction, the push-down record, and binding registration
+// live type-checked in PgQueryResolverEntryPoint_Ops.res.
+
+import { handler as dispatchHandler } from "@reventlessdev/reventless-aws/src/adapter/QueryDb/PgQueryResolver_Lambda.res.mjs";
 import { patchSpecId, log } from "./HandlerFactoryHelpers.mjs";
+import * as Ops from "./PgQueryResolverEntryPoint_Ops.res.mjs";
 
 const dynamicImport = (specifier) => import('/var/task/node_modules/' + specifier);
 
-// A bounded full-materialisation for the list fallback (shapes listPage
-// declines). Kept high; the fallback is only hit for search/searchPrefix/ids/
-// backward pagination, which the AutoUI does not issue for large models.
-const SCAN_ALL_LIMIT = 100000;
-
 async function buildAllBindings() {
-  const configStr = process.env["QUERY_RESOLVER_CONFIG"] || '{"handlers":[]}';
-  const config = JSON.parse(configStr);
+  const config = Ops.parseResolverConfig(process.env["QUERY_RESOLVER_CONFIG"] || "");
   const pgConnection = config.pgConnection;
   if (!pgConnection) {
     log.warn("no pgConnection in QUERY_RESOLVER_CONFIG", { comp: "PgQueryResolver" });
     return;
   }
-  // Container-lifetime pool (memoised by poolFor); the engine and the ops set
-  // share it, so a Lambda holds one pool regardless of read model count.
-  const pool = poolFor(pgConnection);
-  const engine = makeEngine({ pool });
 
-  // Relay node type → read-model map (B3.2c), baked into the config.
-  for (const [typeName, rm] of Object.entries(config.nodeTypes || {})) {
-    registerNodeType(typeName, rm);
-  }
+  Ops.registerNodeTypes(config);
+  const pushdowns = Ops.makePushdowns(pgConnection);
 
-  const pushdowns = {
-    indexLookup: engine.indexLookup,
-    byIds: engine.byIds,
-    listPage: engine.listPage,
-    itemsPage: engine.itemsPage,
-    scanAll: (readModelName) => engine.scan(readModelName, [], SCAN_ALL_LIMIT),
-  };
-
-  await Promise.all((config.handlers || []).map(async h => {
+  await Promise.all(config.handlers.map(async h => {
     const specModule = patchSpecId(await dynamicImport(h.specModule));
-    const indexes = (specModule.config && specModule.config.indexes) || [];
-    const subIdField = specModule.subIdConfig ? specModule.subIdConfig.subIdField : undefined;
-    const capability = deriveServerCapability(specModule.stateSchema);
-    const ops = pgQdbOpsFor(pgConnection, h.readModelName, indexes, subIdField);
-
-    register(h.readModelName, {
-      ops,
-      pushdowns,
-      indexes,
-      subIdField,
-      capability,
-      labelField: h.labelField,
-      includeIdParam: h.includeIdParam,
-      // Compiled string variant (e.g. "AllowAuthenticated"), injected on the
-      // spec by @@reventless.spec — the shape Reventless.Authorization.isAllowed
-      // matches on.
+    Ops.registerBinding(pushdowns, pgConnection, h, {
+      config: specModule.config,
+      subIdConfig: specModule.subIdConfig,
+      stateSchema: specModule.stateSchema,
       authorization: specModule.authorization,
     });
-    log.debug("registered resolver binding for " + h.readModelName, { comp: "PgQueryResolver" });
   }));
 }
 

package/src/adapter/Runtime/PgQueryResolverEntryPoint_Ops.res

@@ -0,0 +1,155 @@
+// Typed cold-start core for the shared PgQueryResolver Lambda entry point
+// (B3.2b).
+//
+// The "typed core, thin shell" split (docs/plans/minimize-lambda-entrypoint-mjs-shell.md):
+// PgQueryResolverEntryPoint.mjs keeps only the untyped seam — the dynamic
+// `import()` of each spec package named in QUERY_RESOLVER_CONFIG, the
+// `patchSpecId` fix-up, and the reads of the runtime-loaded module's exports
+// (config / subIdConfig / stateSchema / authorization), handed back here as a
+// typed `specInfo`. QUERY_RESOLVER_CONFIG parsing, the pool/engine
+// construction (QueryEnginePostgres.Make over an inline module capturing the
+// container-lifetime pool), the push-down record, and the per-read-model
+// binding registration live here, fully type-checked.
+
+@module("./HandlerFactoryHelpers.mjs") @scope("log")
+external logDebug: (string, StreamRoutedEntryPoint_Ops.dispatchOpts) => unit = "debug"
+
+// ── QUERY_RESOLVER_CONFIG ───────────────────────────────────────────────────
+// Written by PgQueryResolver_Builder: one shared pgConnection + one handler
+// per read model + the Relay node type → read-model map (B3.2c).
+
+type handlerEntry = {
+  readModelName: string,
+  specModule: string,
+  labelField: string,
+  includeIdParam: bool,
+}
+
+type resolverConfig = {
+  pgConnection: option<PgConnection.connectionConfig>,
+  handlers: array<handlerEntry>,
+  nodeTypes: dict<string>,
+}
+
+// The builder writes `pgConnection` via PgConnection.connectionConfigToJson, so
+// the parsed object IS the record shape — cast at the documented JSON contract
+// (the AggregateEntryPoint_Ops.asConnectionConfig pattern).
+external asPgConnection: JSON.t => PgConnection.connectionConfig = "%identity"
+
+let strOf = (obj: dict<JSON.t>, key: string): option<string> =>
+  obj->Dict.get(key)->Option.flatMap(JSON.Decode.string)
+
+let decodeEntry = (json: JSON.t): option<handlerEntry> =>
+  json
+  ->JSON.Decode.object
+  ->Option.map(h => {
+    readModelName: h->strOf("readModelName")->Option.getOr(""),
+    specModule: h->strOf("specModule")->Option.getOr(""),
+    labelField: h->strOf("labelField")->Option.getOr(""),
+    includeIdParam: h
+    ->Dict.get("includeIdParam")
+    ->Option.flatMap(JSON.Decode.bool)
+    ->Option.getOr(false),
+  })
+
+let parseResolverConfig = (rawJson: string): resolverConfig => {
+  let obj =
+    (rawJson == "" ? `{"handlers":[]}` : rawJson)
+    ->JSON.parseOrThrow
+    ->JSON.Decode.object
+    ->Option.getOr(Dict.make())
+  {
+    pgConnection: obj
+    ->Dict.get("pgConnection")
+    ->Option.filter(j => j != JSON.Null)
+    ->Option.map(asPgConnection),
+    handlers: obj
+    ->Dict.get("handlers")
+    ->Option.flatMap(JSON.Decode.array)
+    ->Option.getOr([])
+    ->Array.filterMap(decodeEntry),
+    nodeTypes: obj
+    ->Dict.get("nodeTypes")
+    ->Option.flatMap(JSON.Decode.object)
+    ->Option.getOr(Dict.make())
+    ->Dict.toArray
+    ->Array.filterMap(((k, v)) => v->JSON.Decode.string->Option.map(s => (k, s)))
+    ->Dict.fromArray,
+  }
+}
+
+let registerNodeTypes = (config: resolverConfig): unit =>
+  config.nodeTypes
+  ->Dict.toArray
+  ->Array.forEach(((typeName, readModelName)) =>
+    PgQueryResolver_Lambda.registerNodeType(~typeName, ~readModelName)
+  )
+
+// ── Push-downs ──────────────────────────────────────────────────────────────
+
+// A bounded full-materialisation for the list fallback (shapes listPage
+// declines). Kept high; the fallback is only hit for search/searchPrefix/ids/
+// backward pagination, which the AutoUI does not issue for large models.
+let scanAllLimit = 100000
+
+// Container-lifetime pool (memoised by poolFor); the engine and each binding's
+// ops set share it, so the Lambda holds one pool regardless of read model
+// count.
+let makePushdowns = (
+  pgConnection: PgConnection.connectionConfig,
+): PgQueryResolver_Lambda.pushdowns => {
+  module Engine = ReventlessPostgres.QueryEnginePostgres.Make({
+    let pool = PgRuntime.poolFor(pgConnection)
+  })
+  {
+    indexLookup: Engine.indexLookup,
+    byIds: Engine.byIds,
+    listPage: Engine.listPage,
+    itemsPage: Engine.itemsPage,
+    scanAll: (~readModelName) => Engine.scan(~readModelName, ~filterConfigs=[], ~limit=scanAllLimit),
+  }
+}
+
+// ── Binding registration ────────────────────────────────────────────────────
+// The runtime-loaded spec module's exports, read by the shell and passed as a
+// typed record; `authorization` is the compiled string variant (e.g.
+// "AllowAuthenticated") injected on the spec by @@reventless.spec — the shape
+// Reventless.Authorization.isAllowed matches on.
+
+type specInfo = {
+  config: option<ProjectionEntryPoint_Ops.specConfig>,
+  subIdConfig: option<Reventless.ReadModel.subIdConfig<JSON.t>>,
+  stateSchema: S.t<unknown>,
+  authorization: Reventless.Authorization.permission,
+}
+
+let registerBinding = (
+  pushdowns: PgQueryResolver_Lambda.pushdowns,
+  pgConnection: PgConnection.connectionConfig,
+  entry: handlerEntry,
+  spec: specInfo,
+): unit => {
+  let indexes = ProjectionEntryPoint_Ops.indexesOf(spec.config)
+  let subIdField = ProjectionEntryPoint_Ops.subIdFieldOf(spec.subIdConfig)
+  PgQueryResolver_Lambda.register(
+    ~readModelName=entry.readModelName,
+    {
+      ops: QueryDbStorage_Postgres_Runtime.opsFor(
+        pgConnection,
+        ~name=entry.readModelName,
+        ~indexes,
+        ~subIdField=?subIdField,
+      ),
+      pushdowns,
+      indexes,
+      subIdField,
+      capability: ReventlessCore.GraphQL_FragmentGenerator.deriveServerCapability(
+        spec.stateSchema,
+      ),
+      labelField: entry.labelField,
+      includeIdParam: entry.includeIdParam,
+      authorization: spec.authorization,
+    },
+  )
+  logDebug("registered resolver binding for " ++ entry.readModelName, {comp: "PgQueryResolver"})
+}