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

package/src/adapter/Runtime/EventCollectorEntryPoint.mjs

@@ -2,6 +2,15 @@
 // per-plugin EventCollector Lambda. This module is plugin-agnostic: behaviour is
 // driven entirely by HANDLER_CONFIG.
 //
+// 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 EP/extension/spec
+// modules named in HANDLER_CONFIG and the functor applications consuming those
+// runtime-loaded modules. Everything else (config parse/validation, the Plugin-RM
+// projection, the cross-plugin SNS subscription manager, publish/query/scheduler
+// operations, handler-dict assembly, Plugin_Callback wiring, dispatch boundary)
+// lives type-checked in EventCollectorEntryPoint_Ops.res.
+//
 // HANDLER_CONFIG schema (JSON in env var "HANDLER_CONFIG"):
 //
 // {
@@ -9,16 +18,10 @@
 //   "pluginExtensionPointCmdTopicUrl":string  // SQS URL of PlatformPluginExtPoint cmd topic (admin's Plugin EP)
 //   "eventTopicArn":                  string  // SNS ARN the EP's outgoing events publish to ("NOT_AVAILABLE" if none)
 //   "pluginReadModelTableName":       string  // DynamoDB table for Plugin RM (used by QueryEngine.scan)
-//   "pluginSchemaPersistenceTableName":string // DynamoDB table holding deploy-time SDL fragments
-//                                              // (rows keyed "deploy-schema:<name>"). Durable source
-//                                              // for the runtime schema stitch; "NOT_AVAILABLE" →
-//                                              // fall back to Plugin RM Connected-row scan.
 //   "appSyncApiId":                   string  // "NOT_AVAILABLE" disables schema stitching
-//   "clonerEnabled":                  boolean
 //   "schedulerRoleArn":               string  // IAM role for CloudWatch Events schedule targets
 //   "schedulerQueueArn":              string  // ARN of the cmd topic the scheduler publishes to ("" → no commandTopicResources)
 //   "schedulerQueueName":             string
-//   "pluginDefinition":               Plugin.pluginDefinition  // serialized; admin uses a fake one (id="Admin@INTERNAL")
 //   "extensionPoints": [                       // EPs whose OUTGOING events this Lambda processes; admin: 1 entry, plugins: []
 //     {
 //       "specModule":      string,   // dynamic import specifier for the EP spec module
@@ -44,8 +47,7 @@
 //     }
 //   ],
 //   "publishToAggregates": {                   // aggregateName → env-var name holding the aggregate's cmd-topic SQS URL
-//     "Plugin": "PTA_Plugin_QUEUE_URL",
-//     "RecordProductDemand": "PTA_RecordProductDemand_QUEUE_URL"
+//     "Plugin": "PTA_Plugin_QUEUE_URL"
 //   },
 //   "readModelQueueUrls": {                    // rmName → env-var name holding the RM's EventCollector SQS URL
 //     "ProductDemands": "PRM_ProductDemands_QUEUE_URL"
@@ -60,353 +62,16 @@
 // asset (this file). The runtime differences are entirely data — which EPs to
 // process outgoing events for (admin only) and which Connect extension to wire
 // (plugin only). Plugin_Callback.Make routes incoming SQS events to the right
-// service-keyed handler dict; we reconstruct those dicts here from HANDLER_CONFIG.
+// service-keyed handler dict; Ops reconstructs those dicts from what we wire here.
 
-import { readFileSync } from "node:fs";
 import { createRequire } from "node:module";
 import { pathToFileURL } from "node:url";
-import {
-  patchSpecId,
-  makeQueueRef,
-  scanByTableName,
-  log,
-  runEffect,
-  setRequestId,
-  extractMetaField,
-  extractSentTimestamp,
-  extractRetryCount,
-} from "./HandlerFactoryHelpers.mjs";
-import { subscribeQueueToTopic, unsubscribeQueueFromTopic } from "@reventlessdev/rescript-aws-sdk/src/SNS_Helpers.res.mjs";
-import { sendMessage } from "@reventlessdev/reventless-aws/src/plugin/runtime/Util_PluginMessage_Runtime.res.mjs";
-import { publish as snsPublish } from "@reventlessdev/reventless-aws/src/adapter/EventTopic/EventTopicPublisher_SNS_Runtime.res.mjs";
-import { publishJsons as sqsPublishJsons } from "@reventlessdev/reventless-aws/src/adapter/CommandTopic/CommandTopicChannel_SQS_Runtime.res.mjs";
+import { patchSpecId } from "./HandlerFactoryHelpers.mjs";
 import { Make as extensionPointOperationsMake } from "@reventlessdev/reventless-core/src/components/ExtensionPoint/ExtensionPoint_Operations.res.mjs";
 import { Make as extensionOperationsMake } from "@reventlessdev/reventless-core/src/components/Extension/Extension_Operations.res.mjs";
 import { Make as extensionMappingMake } from "@reventlessdev/reventless-infra/src/types/ExtensionMapping.res.mjs";
 import { Make as extensionPointMappingMake } from "@reventlessdev/reventless-infra/src/types/ExtensionPointMapping.res.mjs";
-import { Make as pluginCallbackMake } from "@reventlessdev/reventless-core/src/plugin/component/Plugin_Callback.res.mjs";
-import { handleDynamoDbOrSqsEvent } from "@reventlessdev/reventless-aws/src/adapter/EventCollector/EventCollectorChannel_SQS_Runtime.res.mjs";
-import { createSchedule as cwCreateSchedule, deleteSchedule as cwDeleteSchedule } from "@reventlessdev/reventless-aws/src/adapter/ScheduledPublisher/ScheduledPublisher_CloudWatchEvents_Runtime.res.mjs";
-import {
-  decode as decodeFragment,
-} from "@reventlessdev/reventless-core/src/components/Api/GraphQL_Stitcher.res.mjs";
-
-// The Plugin RM state schema uses `@s.matches(_jsNullable …)` for many
-// optional fields — top-level AND nested. DDB writes drop undefined
-// attributes, so the unmarshalled row arrives with the relevant keys
-// *missing* (not set to null). Sury's strict parser then rejects them as
-// "received undefined". Tracking and patching every nullable path by hand is
-// whack-a-mole; instead, manageSubscriptions and reconcileSubscriptions only
-// need a tiny subset of the state (id / status / extensions / extensionPoints
-// / eventCollector), so they sidestep sury entirely and read the DDB row
-// directly via this small projection.
-function projectPluginRow(row) {
-  if (!row || typeof row !== "object") return null;
-  if (typeof row.id !== "string" || typeof row.status !== "string") return null;
-  const dcbEventLog =
-    row.dcbEventLog &&
-    typeof row.dcbEventLog === "object" &&
-    typeof row.dcbEventLog.name === "string" &&
-    typeof row.dcbEventLog.eventTopicArn === "string"
-      ? { name: row.dcbEventLog.name, eventTopicArn: row.dcbEventLog.eventTopicArn }
-      : null;
-  return {
-    id: row.id,
-    status: row.status,
-    eventCollector: typeof row.eventCollector === "string" ? row.eventCollector : "",
-    extensions: Array.isArray(row.extensions)
-      ? row.extensions
-          .filter((e) => e && typeof e.extensionPointName === "string")
-          .map((e) => ({
-            name: typeof e.name === "string" ? e.name : "",
-            extensionPointName: e.extensionPointName,
-            dcbSources: Array.isArray(e.dcbSources)
-              ? e.dcbSources.filter((s) => typeof s === "string")
-              : [],
-          }))
-      : [],
-    extensionPoints: Array.isArray(row.extensionPoints)
-      ? row.extensionPoints
-          .filter((ep) => ep && typeof ep.name === "string" && typeof ep.eventTopic === "string")
-          .map((ep) => ({
-            name: ep.name,
-            commandTopic: typeof ep.commandTopic === "string" ? ep.commandTopic : "",
-            eventTopic: ep.eventTopic,
-          }))
-      : [],
-    dcbEventLog,
-  };
-}
-
-function parseHandlerConfig(rawJson) {
-  if (!rawJson) throw new Error("HANDLER_CONFIG env var is empty");
-  let config;
-  try {
-    config = JSON.parse(rawJson);
-  } catch (e) {
-    throw new Error("HANDLER_CONFIG JSON parse error: " + (e && e.message));
-  }
-  const required = [
-    "queueUrl",
-    "pluginExtensionPointCmdTopicUrl",
-    "eventTopicArn",
-    "pluginReadModelTableName",
-    "appSyncApiId",
-    "schedulerRoleArn",
-    "schedulerQueueArn",
-    "schedulerQueueName",
-    "extensionPoints",
-    "extensions",
-    "publishToAggregates",
-  ];
-  for (const k of required) {
-    if (config[k] === undefined) {
-      throw new Error("HANDLER_CONFIG missing required field: " + k);
-    }
-  }
-  if (!Array.isArray(config.extensionPoints)) throw new Error("HANDLER_CONFIG.extensionPoints must be an array");
-  if (!Array.isArray(config.extensions)) throw new Error("HANDLER_CONFIG.extensions must be an array");
-  // connectExtension is allowed to be null or absent (admin case)
-  if (config.connectExtension === undefined) config.connectExtension = null;
-  // Optional fields with empty defaults — admin context omits them entirely.
-  if (config.readModelQueueUrls === undefined) config.readModelQueueUrls = {};
-  if (config.readModelNamesForSourceName === undefined) config.readModelNamesForSourceName = {};
-  // Per-extension defaults so older serialisers (or partial admin configs) keep working.
-  for (const ext of config.extensions) {
-    if (!Array.isArray(ext.aggregateNames)) ext.aggregateNames = [];
-    if (!Array.isArray(ext.readModelNames)) ext.readModelNames = [];
-    if (typeof ext.name !== "string") ext.name = ext.extensionPointName || "unknown";
-    if (typeof ext.delegateModule !== "string") ext.delegateModule = "";
-  }
-  return config;
-}
-
-const invalidNameChars = /[^.\-_a-zA-Z0-9]/g;
-const resourceNaming = {
-  validateName: (n) => n.replace(invalidNameChars, "_"),
-  urnName: (arn) => {
-    const parts = arn.split(":");
-    return parts[5] || "unknown";
-  },
-};
-
-// Admin-mediated cross-plugin SNS subscription manager (Plan Phase 3, Step 1).
-// When DoConnectPlugin / DoDisconnectPlugin fires on the admin EP mapping, we
-// scan the Plugin RM for currently-Connected peers and wire (or tear down) SNS
-// subscriptions between this plugin's EventCollector queue and peer plugins'
-// EP event topics — in both directions:
-//   - peer EP topic → this plugin's EC queue, for each of this plugin's
-//     extensions whose `extensionPointName` matches a peer EP
-//   - this plugin's EP topics → peer EC queues, for each peer extension whose
-//     `extensionPointName` matches one of this plugin's EPs
-// subscribeQueueToTopic is idempotent (lists existing subscriptions first);
-// unsubscribeQueueFromTopic is best-effort and swallows the "no subscription"
-// case. Failures are logged but do not throw — admin's RM projection still
-// proceeds and cold-start reconciliation will re-attempt missed work.
-function mkManageSubscriptions(tableName) {
-  if (!tableName || tableName === "NOT_AVAILABLE") return undefined;
-  const trySubscribe = async (queueArn, topicArn, label) => {
-    if (!queueArn || !topicArn) return;
-    try {
-      await subscribeQueueToTopic(queueArn, topicArn);
-      log.info(`subscribed ${label}: ${topicArn} -> ${queueArn}`, { comp: "manageSubscriptions" });
-    } catch (e) {
-      const msg = (e && e.message) || String(e);
-      log.error(`subscribe failed ${label}: ${topicArn} -> ${queueArn}`, { comp: "manageSubscriptions", detail: msg });
-    }
-  };
-  const tryUnsubscribe = async (queueArn, topicArn, label) => {
-    if (!queueArn || !topicArn) return;
-    try {
-      await unsubscribeQueueFromTopic(queueArn, topicArn);
-      log.info(`unsubscribed ${label}: ${topicArn} -> ${queueArn}`, { comp: "manageSubscriptions" });
-    } catch (e) {
-      const msg = (e && e.message) || String(e);
-      log.error(`unsubscribe failed ${label}: ${topicArn} -> ${queueArn}`, { comp: "manageSubscriptions", detail: msg });
-    }
-  };
-  const scanConnectedPeers = async (excludeId) => {
-    const rows = await scanByTableName(
-      tableName,
-      [["status", { TAG: "Contains" }, { TAG: "String", _0: "Connected" }]],
-      1000
-    );
-    const peers = [];
-    for (const row of rows) {
-      const state = projectPluginRow(row);
-      if (state && state.id !== excludeId) peers.push(state);
-    }
-    return peers;
-  };
-  // Extract the plugin display name from a versioned id like "Catalog@1.0.0-alpha.65".
-  const pluginNameOfId = (id) => (typeof id === "string" ? id.split("@")[0] : "");
-  return async (pluginDef, action) => {
-    const isConnect = action === "connect";
-    const op = isConnect ? trySubscribe : tryUnsubscribe;
-    const peers = await scanConnectedPeers(pluginDef.id);
-    // Subscriptions are wired between SNS topics and SQS queues that are owned
-    // per PLUGIN NAME, not per version (the EC queue, EP event topics, and DCB
-    // event topic ARNs all live in the plugin's stack and are stable across
-    // version-to-version upgrades). When a superseded version is Retired and
-    // its row transitions to Disconnected, this hook fires with action="disconnect"
-    // — but if a newer version of the same plugin is still Connected, the
-    // subscriptions are still in use. Tearing them down here would silently
-    // break cross-plugin event flow for the live version (and only cold-start
-    // reconciliation on the surviving plugin would heal it — which happens on
-    // its next Lambda init, not immediately). Skip the tear-down in that case.
-    if (!isConnect) {
-      const myName = pluginNameOfId(pluginDef.id);
-      const liveSibling = peers.find((p) => pluginNameOfId(p.id) === myName);
-      if (liveSibling) {
-        log.info(`disconnect skipped for ${pluginDef.id}: sibling version ${liveSibling.id} still Connected and shares the same EC queue / EP topics`, { comp: "manageSubscriptions" });
-        return;
-      }
-    }
-    // Subscriptions for this plugin's extensions: peer EP topic → this EC queue
-    for (const ext of pluginDef.extensions || []) {
-      for (const peer of peers) {
-        const peerEp = (peer.extensionPoints || []).find(
-          (ep) => ep.name === ext.extensionPointName
-        );
-        if (peerEp) {
-          await op(pluginDef.eventCollector, peerEp.eventTopic, `${ext.extensionPointName} -> ${pluginDef.id}`);
-        }
-      }
-    }
-    // Subscriptions for this plugin's EPs: this EP topic → peer EC queues
-    for (const ep of pluginDef.extensionPoints || []) {
-      for (const peer of peers) {
-        const matchingExt = (peer.extensions || []).find(
-          (e) => e.extensionPointName === ep.name
-        );
-        if (matchingExt) {
-          await op(peer.eventCollector, ep.eventTopic, `${ep.name} -> ${peer.id}`);
-        }
-      }
-    }
-    // ── Phase 4: DCB topic subscriptions ──────────────────────────────────
-    // For each DCB source this plugin's extensions reference, subscribe this
-    // plugin's EventCollector to the owning peer plugin's DCB EventTopic.
-    for (const ext of pluginDef.extensions || []) {
-      for (const dcbSourceName of ext.dcbSources || []) {
-        const peer = peers.find(
-          (p) => p.dcbEventLog && p.dcbEventLog.name === dcbSourceName
-        );
-        if (peer) {
-          await op(
-            pluginDef.eventCollector,
-            peer.dcbEventLog.eventTopicArn,
-            `dcb ${dcbSourceName} -> ${pluginDef.id}`
-          );
-        }
-      }
-    }
-    // If THIS plugin has a DCB EventLog, subscribe each peer plugin's
-    // EventCollector that references it via dcbSources.
-    if (pluginDef.dcbEventLog) {
-      const myDcbName = pluginDef.dcbEventLog.name;
-      for (const peer of peers) {
-        const consuming = (peer.extensions || []).some((e) =>
-          (e.dcbSources || []).includes(myDcbName)
-        );
-        if (consuming) {
-          await op(
-            peer.eventCollector,
-            pluginDef.dcbEventLog.eventTopicArn,
-            `dcb ${myDcbName} -> ${peer.id}`
-          );
-        }
-      }
-    }
-  };
-}
-
-// Cold-start reconciliation — scan the Plugin RM for every Connected plugin
-// and rerun manageSubscriptions(p, "connect") for each. Idempotent at the SNS
-// level (subscribeQueueToTopic dedupes), so this is safe to run repeatedly;
-// it catches subscriptions lost out-of-band (topic deleted+recreated, plugin
-// restarted with a new EC ARN, etc.). Fire-and-forget — admin still serves
-// incoming events while reconciliation completes.
-async function reconcileSubscriptionsOnce(tableName, manageSubscriptions) {
-  if (!tableName || tableName === "NOT_AVAILABLE" || !manageSubscriptions) return;
-  try {
-    const rows = await scanByTableName(
-      tableName,
-      [["status", { TAG: "Contains" }, { TAG: "String", _0: "Connected" }]],
-      1000
-    );
-    for (const row of rows) {
-      const state = projectPluginRow(row);
-      if (state) {
-        try {
-          await manageSubscriptions(state, "connect");
-        } catch (e) {
-          log.warn("manageSubscriptions failed", { comp: "reconcileSubscriptions", detail: (e && e.message) || String(e) });
-        }
-      }
-    }
-  } catch (e) {
-    log.warn("scan failed", { comp: "reconcileSubscriptions", detail: (e && e.message) || String(e) });
-  }
-}
-
-function buildPublishToAggregates(map) {
-  const out = {};
-  for (const [aggName, envVarName] of Object.entries(map || {})) {
-    const queueUrl = process.env[envVarName] || "";
-    out[aggName] = sqsPublishJsons(makeQueueRef(queueUrl), "SQS_FIFO");
-  }
-  return out;
-}
-
-function dictByServiceKeys(serviceKeys, handler) {
-  const dict = {};
-  for (const k of serviceKeys || []) {
-    if (!dict[k]) dict[k] = [];
-    dict[k].push(handler);
-  }
-  return dict;
-}
-
-function mergeDicts(...dicts) {
-  const out = {};
-  for (const d of dicts) {
-    for (const [k, v] of Object.entries(d)) {
-      out[k] = (out[k] || []).concat(v);
-    }
-  }
-  return out;
-}
-
-// pluginDefinition is shipped as a file in the asset zip rather than packed
-// into HANDLER_CONFIG (AWS Lambda's UpdateFunctionConfiguration request has a
-// 5120-byte limit; pluginStructure alone — schemas inline per component —
-// blew past that). The Lambda runtime extracts the zip to /var/task, and the
-// re-export index.mjs lives at /var/task/index.mjs alongside
-// pluginDefinition.json. process.cwd() is /var/task in Lambda, so a relative
-// path resolves correctly. The file is parsed once at cold start.
-function loadPluginDefinition() {
-  try {
-    const raw = readFileSync(new URL("./pluginDefinition.json", `file://${process.cwd()}/`), "utf-8");
-    return JSON.parse(raw);
-  } catch (e) {
-    const msg = (e && e.message) || String(e);
-    throw new Error("Failed to load pluginDefinition.json from asset zip: " + msg);
-  }
-}
-
-// The plugin's UI-fragment manifest — shipped as its own asset since the
-// manifest no longer rides pluginDefinition (the UiFragmentRegistry slice owns
-// fragment state). Contains JSON `null` for plugins without a UI; tolerate a
-// missing file (archives built before the asset existed) the same way.
-function loadUiFragments() {
-  try {
-    const raw = readFileSync(new URL("./uiFragments.json", `file://${process.cwd()}/`), "utf-8");
-    return JSON.parse(raw);
-  } catch (e) {
-    return null;
-  }
-}
+import * as Ops from "./EventCollectorEntryPoint_Ops.res.mjs";
 
 // Cross-plugin spec packages (e.g. "@reventlessdev/online-shop-hybrid-catalog-spec")
 // are bundled into the function asset under /var/task/node_modules/ by
@@ -428,52 +93,13 @@ const importFromAsset = (() => {
 })();
 
 async function buildHandler() {
-  const config = parseHandlerConfig(process.env["HANDLER_CONFIG"]);
-  const pluginDefinition = loadPluginDefinition();
-  // Stack name, not the function name — see PluginExtensionPointEntryPoint for
-  // why the disconnect schedule's rule prefix must not carry a content hash.
-  // Both entry points instantiate the same admin Plugin EP module, so they have
-  // to derive this identically.
-  const environment = process.env["Environment"] || "unknown";
+  const config = Ops.parseHandlerConfig(process.env["HANDLER_CONFIG"] || "");
+  const pluginDefinition = Ops.loadPluginDefinition();
 
-  // runtimeOps carries only what the admin EP mapping's callHandler actually
-  // needs: sendMessageToChannel for ForwardCommand. Cross-plugin SNS
-  // subscription wiring moved to manageSubscriptionsFn (Phase 3 Step 1 +
-  // Step 3) — the topicSubscription stubs that the plugin Connect extension
-  // used to call no longer exist on either side.
-  const runtimeOps = {
-    messagePublish: { sendMessageToChannel: sendMessage },
-  };
-
-  const queryEngine = {
-    scan: (readModelName, filterConfigs, limit) =>
-      scanByTableName(config.pluginReadModelTableName, filterConfigs, limit),
-    query: async () => {
-      throw new Error("QueryEngine.query not available in bundled Plugin EventCollector");
-    },
-  };
-
-  const scheduler = {
-    createSchedule: cwCreateSchedule(config.schedulerRoleArn),
-    deleteSchedule: cwDeleteSchedule,
-  };
-
-  const commandTopicResources = config.schedulerQueueArn !== ""
-    ? [{
-        name: config.schedulerQueueName,
-        id: config.schedulerQueueName,
-        urn: config.schedulerQueueArn,
-        service: "unknown",
-        resourceInfo: "NoInfo",
-        role: "",
-        region: "",
-        resourceType: "",
-        configuration: {},
-        tags: {},
-      }]
-    : [];
-
-  const manageSubscriptionsFn = mkManageSubscriptions(config.pluginReadModelTableName);
+  const queryEngine = Ops.makeQueryEngine(config.pluginReadModelTableName);
+  const scheduler = Ops.makeScheduler(config.schedulerRoleArn);
+  const commandTopicResources = Ops.makeCommandTopicResources(config);
+  const manageSubscriptionsFn = Ops.makeManageSubscriptions(config.pluginReadModelTableName);
 
   // EP operations — admin has 1 entry (Plugin EP), plugins have N user EPs.
   //
@@ -489,8 +115,7 @@ async function buildHandler() {
   //      that declares an ExtensionPoint. The ExtensionPoint spec module is
   //      erased at compile time and must be re-attached at runtime.
   //
-  // Dispatch on `typeof Make === function` to handle both. Mirrors the
-  // user-extensions branch below which already does this for ExtensionMappings.
+  // Dispatch on `typeof Make === function` to handle both.
   const epHandlers = await Promise.all(config.extensionPoints.map(async (ep) => {
     const specMod = patchSpecId(await importFromAsset(ep.specModule));
     const mappingsMod = await importFromAsset(ep.mappingsModule);
@@ -499,12 +124,12 @@ async function buildHandler() {
     if (typeof mappingsMod.Make === "function") {
       // Admin's Plugin EP: invoke the Make functor with runtime ops.
       const epModule = mappingsMod.Make({
-        runtimeOps,
-        environment,
-        // Connect-driven schema self-heal retired (Phase 4b) — the ApiSchemaPush
+        runtimeOps: Ops.runtimeOps,
+        environment: Ops.environment,
+        // Connect-driven schema self-heal retired — the ApiSchemaPush
         // SideEffect on ApiFragmentRegistry events is the single schema writer.
         updateApiSchema: undefined,
-        manageSubscriptions: manageSubscriptionsFn,
+        manageSubscriptions: Ops.manageForDefinition(manageSubscriptionsFn),
       });
       mappingsModule = { mappings: [epModule.Mapping] };
     } else {
@@ -522,55 +147,40 @@ async function buildHandler() {
         Delegate: patchSpecId(mappingsMod.Delegate),
         moduleUrl: ep.mappingsModule,
       };
-      const transformedMapping = extensionPointMappingMake(mappingImpl);
-      mappingsModule = { mappings: [transformedMapping] };
+      mappingsModule = { mappings: [extensionPointMappingMake(mappingImpl)] };
     }
 
-    const resolvedTopic = {
-      name: ep.eventTopicArn,
-      id: ep.eventTopicArn,
-      arn: ep.eventTopicArn,
-    };
     const ops = extensionPointOperationsMake(specMod)(mappingsModule)({
-      publishToEventTopic: (id, meta, json) => snsPublish(resolvedTopic, id, meta, json),
+      publishToEventTopic: Ops.makePublishToEventTopic(ep.eventTopicArn),
       commandTopicResources,
       scheduler,
       queryEngine,
-      resourceNaming,
+      resourceNaming: Ops.resourceNaming,
     });
-    return {
-      aggregateNames: ep.aggregateNames || [],
-      outgoingHandler: ops.outgoingJsonEventsHandler,
-    };
+    return { aggregateNames: ep.aggregateNames, outgoingHandler: ops.outgoingJsonEventsHandler };
   }));
 
-  // Connect extension — exactly one entry per plugin Lambda; null for admin.
-  const publishToAggregates = buildPublishToAggregates(config.publishToAggregates);
-  const publishToPluginExtensionPoint = sqsPublishJsons(
-    makeQueueRef(config.pluginExtensionPointCmdTopicUrl),
-    "SQS_FIFO",
-  );
+  const publishToAggregates = Ops.buildPublishToAggregates(config.publishToAggregates);
+  const publishToPluginExtensionPoint = Ops.makePublishJsons(config.pluginExtensionPointCmdTopicUrl);
 
-  let connectExtensionHandler = null;
+  // Connect extension — exactly one entry per plugin Lambda; null for admin.
+  let connectExtensionHandler = undefined;
   if (config.connectExtension) {
     const ext = config.connectExtension;
     const specMod = patchSpecId(await importFromAsset(ext.specModule));
     const mappingsMod = await importFromAsset(ext.mappingsModule);
-    // After Phase 3 of plugin-eventcollector-runtime-rewire, the Connect
-    // extension Spec carries pluginDefinition plus the plugin's UI-fragment
-    // manifest (its own asset) — cross-plugin subscribe / unsubscribe
-    // directives moved to admin's manageSubscriptions hook. ReScript None
-    // compiles to `undefined`, so map the asset's JSON null accordingly.
+    // The Connect extension Spec carries pluginDefinition plus the plugin's
+    // UI-fragment manifest (its own asset). loadUiFragments returns a ReScript
+    // option — `undefined` (None) for plugins without a UI.
     const extBuilder = mappingsMod.Make({
       pluginDefinition,
-      uiFragments: loadUiFragments() ?? undefined,
+      uiFragments: Ops.loadUiFragments(),
     });
     // PluginConnectExtension_Builder.Make returns a module exposing:
     //   - ConnectPluginMapping  (single mapping)
     //   - ConnectPluginMappings (Mappings module: {Spec, name, mappings, moduleUrl})
     // Use ConnectPluginMappings as the Mappings arg to Extension_Operations.Make.
-    const mappingsModule = extBuilder.ConnectPluginMappings;
-    const ops = extensionOperationsMake(specMod)(mappingsModule)({
+    const ops = extensionOperationsMake(specMod)(extBuilder.ConnectPluginMappings)({
       publishToAggregates,
       publishToPluginExtensionPoint,
       readModelNamesForSourceName: {},
@@ -589,7 +199,7 @@ async function buildHandler() {
   // it through ExtensionMapping.Make, and build per-extension Extension_Operations.
   const userExtensionHandlers = await Promise.all(config.extensions.map(async (ext) => {
     if (!ext.specModule || !ext.mappingsModule || !ext.delegateModule) {
-      log.warn("extension '" + ext.name + "' missing module specifier(s); skipping. specModule=" + ext.specModule + ", mappingsModule=" + ext.mappingsModule + ", delegateModule=" + ext.delegateModule, { comp: "EventCollectorEntryPoint" });
+      Ops.warnSkippedExtension(ext);
       return null;
     }
     const epSpec = patchSpecId(await importFromAsset(ext.specModule));
@@ -615,42 +225,12 @@ async function buildHandler() {
       mappings: [transformedMapping],
     };
 
-    // Per-extension publishToAggregates filtered to ext.aggregateNames —
-    // each aggregate's cmd-topic SQS URL is looked up via the
-    // PTA_<aggName>_QUEUE_URL env var name carried in HANDLER_CONFIG.
-    const extPublishToAggregates = {};
-    for (const aggName of ext.aggregateNames) {
-      const envVarName = config.publishToAggregates[aggName];
-      if (!envVarName) continue;
-      const queueUrl = process.env[envVarName] || "";
-      if (!queueUrl) continue;
-      extPublishToAggregates[aggName] = sqsPublishJsons(makeQueueRef(queueUrl), "SQS_FIFO");
-    }
-
-    // Per-extension publishToReadModels — each RM's EventCollector SQS URL
-    // is looked up via the PRM_<rmName>_QUEUE_URL env var name carried in
-    // HANDLER_CONFIG.readModelQueueUrls.
-    const extPublishToReadModels = {};
-    for (const rmName of ext.readModelNames) {
-      const envVarName = config.readModelQueueUrls[rmName];
-      if (!envVarName) continue;
-      const queueUrl = process.env[envVarName] || "";
-      if (!queueUrl) continue;
-      extPublishToReadModels[rmName] = sqsPublishJsons(makeQueueRef(queueUrl), "SQS_FIFO");
-    }
-
-    // readModelNamesForSourceName scoped to this extension's EP — Extension_Operations
-    // uses this dict to decide which RMs receive each incoming event.
-    const extReadModelNamesForSourceName = {
-      [ext.extensionPointName]:
-        config.readModelNamesForSourceName[ext.extensionPointName] || [],
-    };
-
+    const dicts = Ops.extensionPublishDicts(config, ext);
     const ops = extensionOperationsMake(epSpec)(mappingsModule)({
-      publishToAggregates: extPublishToAggregates,
+      publishToAggregates: dicts.publishToAggregates,
       publishToPluginExtensionPoint,
-      readModelNamesForSourceName: extReadModelNamesForSourceName,
-      publishToReadModels: extPublishToReadModels,
+      readModelNamesForSourceName: dicts.readModelNamesForSourceName,
+      publishToReadModels: dicts.publishToReadModels,
       queryEngine,
     });
 
@@ -661,57 +241,19 @@ async function buildHandler() {
       outgoingHandler: ops.outgoingJsonEventsHandler,
     };
   }));
-  const extensionHandlers = userExtensionHandlers.filter(Boolean);
 
-  // Build the four service-keyed dicts that Plugin_Callback.Make consumes.
-  const outgoingExtensionPointEventHandlers = epHandlers
-    .map((eph) => dictByServiceKeys(eph.aggregateNames, eph.outgoingHandler))
-    .reduce(mergeDicts, {});
-  const incomingConnectExtensionEventHandlers = connectExtensionHandler
-    ? { [connectExtensionHandler.extensionPointName]: [connectExtensionHandler.incomingHandler] }
-    : {};
-  const outgoingExtensionEventHandlers = extensionHandlers
-    .map((eh) => dictByServiceKeys(eh.aggregateNames, eh.outgoingHandler))
-    .reduce(mergeDicts, {});
-  const incomingExtensionEventHandlers = extensionHandlers
-    .map((eh) => ({ [eh.extensionPointName]: [eh.incomingHandler] }))
-    .reduce(mergeDicts, {});
+  // Cold-start reconciliation — awaited so it finishes inside the same
+  // invocation that initialised the Lambda (a floating promise pauses when the
+  // runtime freezes between invocations). Idempotent at the SNS level.
+  await Ops.reconcileSubscriptionsOnce(config.pluginReadModelTableName, manageSubscriptionsFn);
 
-  const callback = pluginCallbackMake({
+  return Ops.makeSqsHandlerBundle({
     pluginDefinition,
-    incomingConnectExtensionEventHandlers,
-    outgoingExtensionPointEventHandlers,
-    outgoingExtensionEventHandlers,
-    incomingExtensionEventHandlers,
+    queueUrl: config.queueUrl,
+    epHandlers,
+    connectExtensionHandler,
+    extensionHandlers: userExtensionHandlers.filter(Boolean),
   });
-
-  // Cold-start reconciliation — awaited so it finishes inside the same
-  // invocation that initialised the Lambda. Fire-and-forget doesn't work on
-  // Lambda: any unfinished promise pauses when the runtime freezes between
-  // invocations and rarely gets a chance to resume. Idempotent at the SNS
-  // level, so the modest extra init latency is paid only on true cold starts.
-  await reconcileSubscriptionsOnce(config.pluginReadModelTableName, manageSubscriptionsFn);
-
-  const sqsHandler = handleDynamoDbOrSqsEvent(makeQueueRef(config.queueUrl), callback.handleJsonEvents);
-  // This module backs both the admin and every per-plugin EventCollector
-  // Lambda, so the comp names the plugin whose events it drains — matching the
-  // `Plugin(<id>)` shape Plugin_Callback logs under.
-  return { sqsHandler, comp: `Plugin(${pluginDefinition.id})` };
 }
 
-const handlerBundlePromise = buildHandler();
-
-export async function handler(event, context) {
-  setRequestId(context?.awsRequestId);
-  const records = event.Records || [];
-  log.debug("processing " + records.length.toString() + " record(s)", { comp: "PluginEventCollectorRuntime" });
-  const { sqsHandler, comp } = await handlerBundlePromise;
-  await runEffect(sqsHandler(event, context), {
-    correlationId: extractMetaField(records, "correlationId"),
-    causationId: extractMetaField(records, "causationId"),
-    comp,
-    timestamp: extractSentTimestamp(records),
-    retryCount: extractRetryCount(records),
-  });
-  return "";
-}
+export const handler = Ops.makeHandler(buildHandler());