@reventlessdev/reventless-aws 3.0.0-alpha.167

package/src/adapter/Runtime/ExtensionPointEntryPoint.mjs

@@ -0,0 +1,101 @@
+// ExtensionPoint Lambda entry point.
+// At cold start: reads HANDLER_CONFIG, dynamically imports Spec/Mappings,
+// wires ExtensionPoint_Callback.Make + CommandTopic_Callback.Make,
+// routes SQS events through handleQueueEvent.
+
+import * as Effect from "effect/Effect";
+import { patchSpecId, makeQueueRef, log, pluginName } from "./HandlerFactoryHelpers.mjs";
+import { tag as requestContextTag } from "@reventlessdev/reventless-core/src/RequestContext.res.mjs";
+import { Make as extensionPointCallbackMake } from "@reventlessdev/reventless-core/src/components/ExtensionPoint/ExtensionPoint_Callback.res.mjs";
+import { Make as commandTopicCallbackMake } from "@reventlessdev/reventless-core/src/components/CommandTopic/CommandTopic_Callback.res.mjs";
+import { handleQueueEvent, publishJsons as sqsPublishJsons } from "@reventlessdev/reventless-aws/src/adapter/CommandTopic/CommandTopicChannel_SQS_Runtime.res.mjs";
+
+const dynamicImport = (specifier) => import('/var/task/node_modules/' + specifier);
+
+// Set at handler entry; read by runEffect to tag logs with the Lambda request id.
+let _currentRequestId = "unknown";
+
+function runEffect(correlationId, effect) {
+  let e = effect
+    // Promote correlationId/requestId/plugin to top-level JSON log fields —
+    // decoded by EffectLogger.install() from Effect log annotations. Harmless
+    // no-op if the unified logger isn't installed.
+    .pipe(Effect.annotateLogs("correlationId", correlationId || "unknown"))
+    .pipe(Effect.annotateLogs("requestId", _currentRequestId));
+  if (pluginName) e = e.pipe(Effect.annotateLogs("plugin", pluginName));
+  return e
+    .pipe(Effect.provideService(requestContextTag, { correlationId: correlationId || "unknown" }))
+    .pipe(Effect.runPromise);
+}
+
+function extractCorrelationId(records) {
+  const first = records[0];
+  if (!first) return undefined;
+  const body = first.body;
+  if (!body) return undefined;
+  try {
+    const parsed = JSON.parse(body);
+    if (typeof parsed === "object" && parsed !== null) {
+      const meta = parsed.meta;
+      if (meta && typeof meta === "object" && typeof meta.correlationId === "string") {
+        return meta.correlationId;
+      }
+    }
+  } catch (_) {}
+  return undefined;
+}
+
+async function buildHandler() {
+  const configStr = process.env["HANDLER_CONFIG"] || "{}";
+  const config = JSON.parse(configStr);
+
+  const specModule = await dynamicImport(config.specModule);
+  const mappingsModule = await dynamicImport(config.mappingsModule);
+
+  const patchedSpec = patchSpecId(specModule);
+
+  // Build publishToAggregates dict from env var queue URLs. The deploy-side
+  // builder writes HANDLER_CONFIG.publishToAggregates as { aggregateName: envVarName }
+  // (see ExtensionPointRuntime_Builder_PerExtensionPoint.res), so iterate accordingly.
+  const publishToAggregates = {};
+  for (const [aggName, envVarName] of Object.entries(config.publishToAggregates || {})) {
+    const queueUrl = process.env[envVarName] || "";
+    publishToAggregates[aggName] = sqsPublishJsons(makeQueueRef(queueUrl), "SQS_FIFO");
+  }
+
+  const callbackConfig = {
+    publishToAggregates,
+    commandTopicResources: [],
+    scheduler: {
+      create: async () => { throw new Error("Scheduler not available in bundled ExtensionPoint handler"); },
+      delete: async () => { throw new Error("Scheduler not available in bundled ExtensionPoint handler"); },
+    },
+    queryEngine: {
+      scan: async () => { throw new Error("QueryEngine not available in bundled ExtensionPoint handler"); },
+      query: async () => { throw new Error("QueryEngine not available in bundled ExtensionPoint handler"); },
+    },
+    resourceNaming: { name: (n) => n, resolve: (n) => n },
+  };
+
+  const callback = extensionPointCallbackMake(callbackConfig)(patchedSpec)(mappingsModule);
+  const commandTopicCallback = commandTopicCallbackMake(patchedSpec)({
+    Spec: patchedSpec,
+    commandsHandler: callback.handleIncomingCommands,
+  });
+
+  const resolvedQueue = makeQueueRef(config.queueUrl);
+  return handleQueueEvent(resolvedQueue, commandTopicCallback.handleJsonCommands);
+}
+
+const initPromise = buildHandler();
+
+export async function handler(event, context) {
+  _currentRequestId = context?.awsRequestId || "unknown";
+  const sqsHandler = await initPromise;
+  const records = event.Records || [];
+  const correlationId = extractCorrelationId(records);
+
+  log.debug("processing " + records.length.toString() + " record(s)", { comp: "ExtensionPointRuntime" });
+  await runEffect(correlationId, sqsHandler(event, context));
+  return "";
+}

package/src/adapter/Runtime/ExtensionPointRuntime_Builder_PerExtensionPoint.res

@@ -0,0 +1,83 @@
+module CommandTopicChannel = CommandTopicChannel.SQS_Sync
+module RuntimeEnvironment = RuntimeEnvironment.Lambda
+
+type context = PulumiAws.Lambda.context
+type runtimeParts = Util.Lambda.runtimeParts
+
+let forCommandTopic = (
+  ~handler as _,
+  ~connect,
+  ~memorySize=1024,
+  ~timeout=30,
+  ~specModulePath as specModuleUrl,
+  ~mappingsModulePath as mappingsModuleUrl,
+  ~publishToAggregatesQueueUrls,
+  commandTopic,
+) => {
+  let commandTopicResource = commandTopic->ReventlessCore.Component.toPulumiResource
+  let channel = commandTopic->ReventlessCore.CommandTopic_Adapter.channel
+  let channelParts: Util.SQS.channelParts = Obj.magic(channel.parts)
+  let queue = channelParts.queue
+
+  // The EP command-handler Lambda inherits the bare EP CommandTopic resource
+  // name (`<EP>ExtPoint`) and appends the unified `CmdHandler` kind so it is
+  // greppable alongside the aggregate/DCB command handlers (analysis §8.2).
+  let name = commandTopicResource.name->Option.getOr("UnnamedExtPoint") ++ "CmdHandler"
+  let opts = {Pulumi.ComponentResource.parent: commandTopicResource}
+
+  let specModulePath = Util_Bundle.getModuleSpecifier(specModuleUrl)
+  let mappingsModulePath = Util_Bundle.getModuleSpecifier(mappingsModuleUrl)
+
+  // Build HANDLER_CONFIG with publishToAggregates mapping aggregate names to env var names
+  let envVars: dict<Pulumi.Input.t<string>> = Dict.make()
+  envVars->Dict.set("EP_QUEUE_URL", queue.id->Pulumi.Output.asInput)
+
+  let publishToAggregatesEnvVars: dict<string> = Dict.make()
+  publishToAggregatesQueueUrls->Dict.forEachWithKey((queueUrlOutput, aggName) => {
+    let envVar = `PTA_${aggName}_QUEUE_URL`
+    envVars->Dict.set(envVar, queueUrlOutput->Pulumi.Output.asInput)
+    publishToAggregatesEnvVars->Dict.set(aggName, envVar)
+  })
+
+  let specModule = specModulePath->JSON.stringifyAny->Option.getOr(`""`)
+  let mappingsModule = mappingsModulePath->JSON.stringifyAny->Option.getOr(`""`)
+  let publishToAggregatesJson =
+    publishToAggregatesEnvVars
+    ->Dict.toArray
+    ->Array.map(((aggName, envVar)) =>
+      `${aggName->JSON.stringifyAny->Option.getOr(`""`)}: ${envVar->JSON.stringifyAny->Option.getOr(`""`)}`
+    )
+    ->Array.join(",")
+
+  let handlerConfigJson =
+    queue.id
+    ->Pulumi.Output.apply(queueUrl =>
+      `{"specModule":${specModule},"mappingsModule":${mappingsModule},"queueUrl":"${queueUrl}","publishToAggregates":{${publishToAggregatesJson}}}`
+    )
+  envVars->Dict.set("HANDLER_CONFIG", handlerConfigJson->Pulumi.Output.asInput)
+
+  // Collect unique user packages for the code asset
+  let packageDirs: dict<string> = Dict.make()
+  let specPkg = Util_Bundle.extractPackageName(specModulePath)
+  let mappingsPkg = Util_Bundle.extractPackageName(mappingsModulePath)
+  packageDirs->Dict.set(specPkg, Util_Bundle.resolvePackageRoot(specPkg))
+  packageDirs->Dict.set(mappingsPkg, Util_Bundle.resolvePackageRoot(mappingsPkg))
+
+  let {code, sourceCodeHash} = Util_Bundle.buildCodeArchive(
+    ~entryPointModule="@reventlessdev/reventless-aws/src/adapter/Runtime/ExtensionPointEntryPoint.mjs",
+    ~packageDirs,
+  )
+
+  let runtime = RuntimeEnvironment_Lambda.makeFromCodeAsset(
+    ~name,
+    ~code,
+    ~sourceCodeHash,
+    ~envVars,
+    ~memorySize,
+    ~timeout,
+    ~opts,
+  )
+  connect(~runtime)
+}
+
+let finish = () => ()

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

@@ -0,0 +1,59 @@
+// Generated by ReScript, PLEASE EDIT WITH CARE
+
+import * as Stdlib_Dict from "@rescript/runtime/lib/es6/Stdlib_Dict.js";
+import * as Stdlib_Option from "@rescript/runtime/lib/es6/Stdlib_Option.js";
+import * as Component$ReventlessCore from "@reventlessdev/reventless-core/src/components/Component.res.mjs";
+import * as Util_Bundle$ReventlessAws from "../../util/Util_Bundle.res.mjs";
+import * as RuntimeEnvironment_Lambda$ReventlessAws from "./RuntimeEnvironment_Lambda.res.mjs";
+
+function forCommandTopic(param, connect, memorySizeOpt, timeoutOpt, specModuleUrl, mappingsModuleUrl, publishToAggregatesQueueUrls, commandTopic) {
+  let memorySize = memorySizeOpt !== undefined ? memorySizeOpt : 1024;
+  let timeout = timeoutOpt !== undefined ? timeoutOpt : 30;
+  let commandTopicResource = Component$ReventlessCore.toPulumiResource(commandTopic);
+  let channel = commandTopic.channel;
+  let channelParts = channel.parts;
+  let queue = channelParts.queue;
+  let name = Stdlib_Option.getOr(commandTopicResource.__name, "UnnamedExtPoint") + "CmdHandler";
+  let opts_parent = commandTopicResource;
+  let opts = {
+    parent: opts_parent
+  };
+  let specModulePath = Util_Bundle$ReventlessAws.getModuleSpecifier(specModuleUrl);
+  let mappingsModulePath = Util_Bundle$ReventlessAws.getModuleSpecifier(mappingsModuleUrl);
+  let envVars = {};
+  envVars["EP_QUEUE_URL"] = queue.id;
+  let publishToAggregatesEnvVars = {};
+  Stdlib_Dict.forEachWithKey(publishToAggregatesQueueUrls, (queueUrlOutput, aggName) => {
+    let envVar = `PTA_` + aggName + `_QUEUE_URL`;
+    envVars[envVar] = queueUrlOutput;
+    publishToAggregatesEnvVars[aggName] = envVar;
+  });
+  let specModule = Stdlib_Option.getOr(JSON.stringify(specModulePath), `""`);
+  let mappingsModule = Stdlib_Option.getOr(JSON.stringify(mappingsModulePath), `""`);
+  let publishToAggregatesJson = Object.entries(publishToAggregatesEnvVars).map(param => Stdlib_Option.getOr(JSON.stringify(param[0]), `""`) + `: ` + Stdlib_Option.getOr(JSON.stringify(param[1]), `""`)).join(",");
+  let handlerConfigJson = queue.id.apply(queueUrl => `{"specModule":` + specModule + `,"mappingsModule":` + mappingsModule + `,"queueUrl":"` + queueUrl + `","publishToAggregates":{` + publishToAggregatesJson + `}}`);
+  envVars["HANDLER_CONFIG"] = handlerConfigJson;
+  let packageDirs = {};
+  let specPkg = Util_Bundle$ReventlessAws.extractPackageName(specModulePath);
+  let mappingsPkg = Util_Bundle$ReventlessAws.extractPackageName(mappingsModulePath);
+  packageDirs[specPkg] = Util_Bundle$ReventlessAws.resolvePackageRoot(specPkg);
+  packageDirs[mappingsPkg] = Util_Bundle$ReventlessAws.resolvePackageRoot(mappingsPkg);
+  let match = Util_Bundle$ReventlessAws.buildCodeArchive("@reventlessdev/reventless-aws/src/adapter/Runtime/ExtensionPointEntryPoint.mjs", packageDirs, undefined);
+  return connect(RuntimeEnvironment_Lambda$ReventlessAws.makeFromCodeAsset(name, match.code, match.sourceCodeHash, envVars, memorySize, timeout, undefined, undefined, undefined, undefined, opts));
+}
+
+function finish() {
+  
+}
+
+let CommandTopicChannel;
+
+let RuntimeEnvironment;
+
+export {
+  CommandTopicChannel,
+  RuntimeEnvironment,
+  forCommandTopic,
+  finish,
+}
+/* Component-ReventlessCore Not a pure module */

package/src/adapter/Runtime/HandlerFactoryHelpers.mjs

@@ -0,0 +1,142 @@
+// Shared runtime utilities for compiled Lambda entry points.
+
+import { $$String as IdString } from "@reventlessdev/reventless-spec/src/types/Id.res.mjs";
+import { DynamoDBClient } from "@aws-sdk/client-dynamodb";
+import { DynamoDBDocumentClient, ScanCommand } from "@aws-sdk/lib-dynamodb";
+
+// ─── Structured logging from the .mjs entry-point shims ─────────────────────
+// Mirrors ReScript's Logger.t API and Logger.emit's JSON sink shape (time,
+// level, message, service, plugin, comp, detail) so shim-side init/error
+// traces land alongside ReScript logs as homogeneous JSON in CloudWatch.
+//
+// Usage: `log.debug("msg", { comp: "AggregateRuntime" })` —
+// level-specific method, no stringly-typed level argument.
+
+const LEVEL_DEBUG = 0;
+const LEVEL_INFO = 1;
+const LEVEL_WARN = 2;
+const LEVEL_ERROR = 3;
+const LEVEL_SILENT = 99;
+
+function envMinLevel() {
+  switch ((process.env.LOG_LEVEL || "info").toLowerCase()) {
+    case "silent": return LEVEL_SILENT;
+    case "debug":  return LEVEL_DEBUG;
+    case "warn":   return LEVEL_WARN;
+    case "error":  return LEVEL_ERROR;
+    default:       return LEVEL_INFO;
+  }
+}
+
+// Per-plugin Lambdas follow the naming pattern `<Plugin>Plugin<Suffix>` (e.g.
+// `CatalogPluginEventColl`, `OrderingPluginHeartbeat`). Multi-plugin Lambdas
+// (`AllAggregatesCmdHandler`, `AllReadModels`, the platform-level `PluginAggr*`)
+// don't carry a single plugin identity; returns null so callers omit the field.
+export function derivePluginFromLambdaName(name) {
+  if (typeof name !== "string") return null;
+  const match = /^([A-Z][a-zA-Z0-9]+)Plugin(?:[A-Z]|$|-)/.exec(name);
+  return match ? match[1] : null;
+}
+
+const PLUGIN_NAME = derivePluginFromLambdaName(process.env.AWS_LAMBDA_FUNCTION_NAME);
+const SERVICE_NAME = process.env.REVENTLESS_SERVICE || process.env.AWS_LAMBDA_FUNCTION_NAME;
+
+function emit(level, levelLabel, message, extra) {
+  if (level < envMinLevel()) return;
+  const fields = { time: new Date().toISOString(), level: levelLabel, message };
+  if (SERVICE_NAME) fields.service = SERVICE_NAME;
+  if (PLUGIN_NAME) fields.plugin = PLUGIN_NAME;
+  if (extra && typeof extra === "object") {
+    for (const [k, v] of Object.entries(extra)) {
+      if (v !== undefined && v !== null) fields[k] = v;
+    }
+  }
+  // eslint-disable-next-line no-console
+  console.log(JSON.stringify(fields));
+}
+
+export const log = {
+  debug: (message, extra) => emit(LEVEL_DEBUG, "DEBUG", message, extra),
+  info:  (message, extra) => emit(LEVEL_INFO,  "INFO",  message, extra),
+  warn:  (message, extra) => emit(LEVEL_WARN,  "WARN",  message, extra),
+  error: (message, extra) => emit(LEVEL_ERROR, "ERROR", message, extra),
+};
+
+// Plugin name derived from the Lambda function name (null on multi-plugin
+// Lambdas). Export so shim runEffect wrappers can annotate Effect logs with it.
+export const pluginName = PLUGIN_NAME;
+
+// Patch a spec module's Id field to use IdString if undefined.
+// Workaround for `module Id = Id.String` not producing an ESM export.
+export const patchSpecId = (specModule) => ({ ...specModule, Id: specModule.Id || IdString });
+
+// Create a minimal DynamoDB table stub from a table name.
+export function makeTableRef(name) {
+  return { name, hashKey: "id" };
+}
+
+// Create a minimal SQS queue stub from a queue URL.
+export function makeQueueRef(url) {
+  return { id: url, name: url, arn: "" };
+}
+
+// DynamoDB scan with filter expression support.
+export async function scanByTableName(tableName, filterConfigs, limit) {
+  if (!scanByTableName._client) {
+    scanByTableName._client = DynamoDBDocumentClient.from(new DynamoDBClient({}));
+  }
+  var client = scanByTableName._client;
+  var filterParts = [];
+  var attrNames = {};
+  var attrValues = {};
+
+  (filterConfigs || []).forEach(function(entry, idx) {
+    var fieldName = entry[0];
+    var comparator = entry[1];
+    var value = entry[2];
+    var valueName = fieldName + idx;
+    attrNames["#" + fieldName] = fieldName;
+
+    var attrValue;
+    if (typeof value === "object" && value !== null && "TAG" in value) {
+      attrValue = value._0;
+    } else {
+      attrValue = value;
+    }
+    attrValues[":" + valueName] = attrValue;
+
+    var comp = typeof comparator === "object" ? comparator.TAG || comparator : comparator;
+    switch (comp) {
+      case "Equal": filterParts.push("#" + fieldName + " = :" + valueName); break;
+      case "Unequal": filterParts.push("#" + fieldName + " <> :" + valueName); break;
+      case "Contains": filterParts.push("contains( #" + fieldName + ", :" + valueName + " )"); break;
+      case "NotContains": filterParts.push("NOT contains( #" + fieldName + ", :" + valueName + " )"); break;
+      case "BeginsWith": filterParts.push("begins_with( #" + fieldName + ", :" + valueName + " )"); break;
+      case "Exists": filterParts.push("attribute_exists( #" + fieldName + " )"); break;
+      case "NotExists": filterParts.push("attribute_not_exists( #" + fieldName + " )"); break;
+      case "LessOrEqual": filterParts.push("#" + fieldName + " <= :" + valueName); break;
+      case "Less": filterParts.push("#" + fieldName + " < :" + valueName); break;
+      case "GreaterOrEqual": filterParts.push("#" + fieldName + " >= :" + valueName); break;
+      case "Greater": filterParts.push("#" + fieldName + " > :" + valueName); break;
+      default: filterParts.push("#" + fieldName + " = :" + valueName);
+    }
+  });
+
+  var params = { TableName: tableName, Limit: limit };
+  if (filterParts.length > 0) {
+    params.FilterExpression = filterParts.join(" AND ");
+    params.ExpressionAttributeNames = attrNames;
+    params.ExpressionAttributeValues = attrValues;
+  }
+
+  var items = [];
+  var lastKey;
+  do {
+    if (lastKey) params.ExclusiveStartKey = lastKey;
+    var result = await client.send(new ScanCommand(params));
+    if (result.Items) items.push.apply(items, result.Items);
+    lastKey = result.LastEvaluatedKey;
+  } while (lastKey && items.length < limit);
+
+  return items;
+}

package/src/adapter/Runtime/HeartbeatEntryPoint.mjs

@@ -0,0 +1,38 @@
+// Heartbeat Lambda handler.
+// Publishes a Heartbeat(timeout) command to the PluginExtensionPoint CommandTopic.
+// Triggered by CloudWatch Events on a schedule.
+
+import { reverseConvertToJsonOrThrow } from "sury/src/S.res.mjs";
+import { makeQueueRef } from "./HandlerFactoryHelpers.mjs";
+import { uuid } from "@reventlessdev/reventless-core/src/Message.res.mjs";
+import { name as pluginExtensionPointName, commandSchema } from "@reventlessdev/reventless-infra/src/types/PluginExtensionPointSpec.res.mjs";
+import { publishJsons as sqsPublishJsons } from "@reventlessdev/reventless-aws/src/adapter/CommandTopic/CommandTopicChannel_SQS_Runtime.res.mjs";
+
+// === Initialize eagerly at module load (Lambda cold start) ===
+
+const epQueueUrl = process.env["EP_QUEUE_URL"] || "";
+const pluginId = process.env["PLUGIN_ID"] || "";
+const timeout = parseInt(process.env["HEARTBEAT_TIMEOUT"], 10) || 10;
+
+const publishJsons = sqsPublishJsons(makeQueueRef(epQueueUrl), "SQS_FIFO");
+
+// === Exported handler ===
+
+export async function handler(_event, _context) {
+  const msgId = uuid();
+  const commandJson = reverseConvertToJsonOrThrow({ TAG: "Heartbeat", _0: timeout }, commandSchema);
+  const message = {
+    id: pluginId,
+    meta: {
+      service: pluginExtensionPointName,
+      time: new Date().toISOString(),
+      ip: "",
+      user: "Heartbeat",
+      msgId,
+      correlationId: msgId,
+    },
+    commandJson,
+  };
+  await publishJsons([message]);
+  return "";
+}

package/src/adapter/Runtime/PluginExtensionPointEntryPoint.mjs

@@ -0,0 +1,137 @@
+// PluginExtensionPoint Lambda entry point.
+// All imports are framework packages — no user modules needed.
+// Handles Heartbeat, Cloner, and other plugin-level extension point commands.
+
+import * as Effect from "effect/Effect";
+import { patchSpecId, makeQueueRef, scanByTableName, log, pluginName } from "./HandlerFactoryHelpers.mjs";
+import { tag as requestContextTag } from "@reventlessdev/reventless-core/src/RequestContext.res.mjs";
+import { sendMessage } from "@reventlessdev/reventless-aws/src/plugin/runtime/Util_PluginMessage_Runtime.res.mjs";
+import * as PluginExtensionPointSpec from "@reventlessdev/reventless-infra/src/types/PluginExtensionPointSpec.res.mjs";
+import { Make as pluginEPPluginMake } from "@reventlessdev/reventless-core/src/plugin/connect/PluginExtensionPoint_Plugin.res.mjs";
+import { Make as extensionPointCallbackMake } from "@reventlessdev/reventless-core/src/components/ExtensionPoint/ExtensionPoint_Callback.res.mjs";
+import { Make as commandTopicCallbackMake } from "@reventlessdev/reventless-core/src/components/CommandTopic/CommandTopic_Callback.res.mjs";
+import { handleQueueEvent, publishJsons as sqsPublishJsons } from "@reventlessdev/reventless-aws/src/adapter/CommandTopic/CommandTopicChannel_SQS_Runtime.res.mjs";
+import { createSchedule as cwCreateSchedule, deleteSchedule as cwDeleteSchedule } from "@reventlessdev/reventless-aws/src/adapter/ScheduledPublisher/ScheduledPublisher_CloudWatchEvents_Runtime.res.mjs";
+
+// Set at handler entry; read by runEffect to tag logs with the Lambda request id.
+let _currentRequestId = "unknown";
+
+function runEffect(correlationId, effect) {
+  let e = effect
+    // Promote correlationId/requestId/plugin to top-level JSON log fields —
+    // decoded by EffectLogger.install() from Effect log annotations. Harmless
+    // no-op if the unified logger isn't installed.
+    .pipe(Effect.annotateLogs("correlationId", correlationId || "unknown"))
+    .pipe(Effect.annotateLogs("requestId", _currentRequestId));
+  if (pluginName) e = e.pipe(Effect.annotateLogs("plugin", pluginName));
+  return e
+    .pipe(Effect.provideService(requestContextTag, { correlationId: correlationId || "unknown" }))
+    .pipe(Effect.runPromise);
+}
+
+function extractCorrelationId(records) {
+  const first = records[0];
+  if (!first) return undefined;
+  const body = first.body;
+  if (!body) return undefined;
+  try {
+    const parsed = JSON.parse(body);
+    if (typeof parsed === "object" && parsed !== null) {
+      const meta = parsed.meta;
+      if (meta && typeof meta === "object" && typeof meta.correlationId === "string") {
+        return meta.correlationId;
+      }
+    }
+  } catch (_) {}
+  return undefined;
+}
+
+function buildHandler() {
+  const configStr = process.env["HANDLER_CONFIG"] || "{}";
+  const config = JSON.parse(configStr);
+
+  const patchedSpec = patchSpecId(PluginExtensionPointSpec);
+
+  // Reconstruct runtimeOps — only sendMessageToChannel is used by this
+  // Lambda's incoming-command path (ForwardCommand). Cross-plugin
+  // subscribe / unsubscribe directives were retired in Phase 3 Step 3.
+  const runtimeOps = {
+    messagePublish: { sendMessageToChannel: sendMessage },
+  };
+
+  // Instantiate Plugin EP mapping. updateApiSchema and manageSubscriptions are
+  // admin-only hooks; this Lambda only handles incoming commands (Heartbeat,
+  // ForwardCommand) so they stay undefined here.
+  const lambdaFunctionName = process.env["AWS_LAMBDA_FUNCTION_NAME"] || "unknown";
+  const pluginModule = pluginEPPluginMake({
+    runtimeOps,
+    environment: lambdaFunctionName,
+    updateApiSchema: undefined,
+    manageSubscriptions: undefined,
+  });
+  const mappingsModule = { mappings: [pluginModule.Mapping] };
+
+  // Reconstruct publishToAggregates. The deploy-side builder writes
+  // HANDLER_CONFIG.publishToAggregates as { aggregateName: envVarName }
+  // (see PluginExtensionPointRuntime_Builder.res), so iterate accordingly.
+  const publishToAggregates = {};
+  for (const [aggName, envVarName] of Object.entries(config.publishToAggregates || {})) {
+    const queueUrl = process.env[envVarName] || "";
+    publishToAggregates[aggName] = sqsPublishJsons(makeQueueRef(queueUrl), "SQS_FIFO");
+  }
+
+  // Reconstruct queryEngine
+  const queryEngine = {
+    scan: (readModelName, filterConfigs, limit) => scanByTableName(config.pluginReadModelTableName, filterConfigs, limit),
+    query: async () => { throw new Error("QueryEngine.query not available in bundled Plugin EP handler"); },
+  };
+
+  // Reconstruct scheduler
+  const scheduler = {
+    createSchedule: cwCreateSchedule(config.schedulerRoleArn),
+    deleteSchedule: cwDeleteSchedule,
+  };
+
+  // CommandTopic resources for scheduler targets
+  const commandTopicResources = config.schedulerQueueArn !== ""
+    ? [{
+        name: config.schedulerQueueName,
+        id: config.schedulerQueueName,
+        urn: config.schedulerQueueArn,
+        service: "unknown",
+        resourceInfo: "NoInfo",
+        role: "",
+        region: "",
+        resourceType: "",
+        configuration: {},
+        tags: {},
+      }]
+    : [];
+
+  const invalidNameChars = /[^.\-_a-zA-Z0-9]/g;
+  const resourceNaming = {
+    validateName: (n) => n.replace(invalidNameChars, "_"),
+    urnName: (arn) => { const parts = arn.split(":"); return parts[5] || "unknown"; },
+  };
+
+  const callbackConfig = { publishToAggregates, commandTopicResources, scheduler, queryEngine, resourceNaming };
+  const callback = extensionPointCallbackMake(callbackConfig)(patchedSpec)(mappingsModule);
+  const commandTopicCallback = commandTopicCallbackMake(patchedSpec)({
+    Spec: patchedSpec,
+    commandsHandler: callback.handleIncomingCommands,
+  });
+
+  return handleQueueEvent(makeQueueRef(config.queueUrl), commandTopicCallback.handleJsonCommands);
+}
+
+const sqsHandler = buildHandler();
+
+export async function handler(event, context) {
+  _currentRequestId = context?.awsRequestId || "unknown";
+  const records = event.Records || [];
+  const correlationId = extractCorrelationId(records);
+
+  log.debug("processing " + records.length.toString() + " record(s)", { comp: "PluginExtensionPointRuntime" });
+  await runEffect(correlationId, sqsHandler(event, context));
+  return "";
+}