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

package/src/adapter/Runtime/SideEffectEntryPoint.mjs

@@ -1,82 +1,41 @@
 // SideEffectHandler Lambda entry point.
 // At cold start: reads HANDLER_CONFIG, dynamically imports SideEffect modules,
 // wires SideEffectHandler_Callback.Make, builds handler map keyed by source URN.
+//
+// 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 side-effect
+// modules named in HANDLER_CONFIG and the SideEffectHandler_Callback.Make
+// functor application consuming them. HANDLER_CONFIG parsing and handler
+// registration live type-checked in SideEffectEntryPoint_Ops.res; the routed
+// dispatch boundary in StreamRoutedEntryPoint_Ops.res.
 
-import {
-  log,
-  runEffect,
-  setRequestId,
-  extractMetaField,
-  extractSentTimestamp,
-  extractRetryCount,
-} from "./HandlerFactoryHelpers.mjs";
 import { Make as sideEffectHandlerCallbackMake } from "@reventlessdev/reventless-core/src/components/SideEffectHandler/SideEffectHandler_Callback.res.mjs";
-import { handleStreamEvent } from "@reventlessdev/reventless-aws/src/adapter/EventCollector/EventCollectorChannel_DynamoDbStream_Runtime.res.mjs";
+import * as StreamOps from "./StreamRoutedEntryPoint_Ops.res.mjs";
+import * as Ops from "./SideEffectEntryPoint_Ops.res.mjs";
 
 const dynamicImport = (specifier) => import('/var/task/node_modules/' + specifier);
 
-function groupBySource(records) {
-  const dict = {};
-  records.forEach(record => {
-    const arn = record.eventSourceARN;
-    const existing = dict[arn] || [];
-    dict[arn] = existing.concat([record]);
-  });
-  return dict;
-}
-
 async function buildAllHandlers() {
-  const configStr = process.env["HANDLER_CONFIG"] || '{"handlers":[]}';
-  const config = JSON.parse(configStr);
   const handlers = {};
+  const entries = Ops.parseHandlerConfig(process.env["HANDLER_CONFIG"] || "");
 
-  await Promise.all(config.handlers.map(async h => {
+  await Promise.all(entries.map(async (entry) => {
     const sideEffectModules = await Promise.all(
-      h.sideEffectModules.map(async modPath => await dynamicImport(modPath))
+      entry.sideEffectModules.map(async modPath => await dynamicImport(modPath))
+    );
+    const callback = sideEffectHandlerCallbackMake({
+      sideEffects: sideEffectModules,
+      queryEngine: Ops.noopQueryEngine,
+    });
+    StreamOps.addToRegistry(
+      handlers,
+      entry.sourceUrn,
+      Ops.makeRegisteredHandler(entry, callback.handleJsonEvents)
     );
-    const noOpQueryEngine = { scan: async () => [], query: async () => [] };
-    const callback = sideEffectHandlerCallbackMake({ sideEffects: sideEffectModules, queryEngine: noOpQueryEngine });
-    const handler = (event, context) => handleStreamEvent(callback.handleJsonEvents, event, context);
-    // Multiple side-effect handlers can share one source stream. Accumulate all
-    // per source ARN; a plain assignment collapses them to one (Promise.all
-    // race), silently dropping the rest. `comp`/`plugin` come from
-    // HANDLER_CONFIG — the shell has only module paths to identify a handler by.
-    (handlers[h.sourceUrn] ||= []).push({ handler, comp: h.comp, plugin: h.plugin });
   }));
 
   return handlers;
 }
 
-const initPromise = buildAllHandlers();
-
-export async function handler(event, context) {
-  setRequestId(context?.awsRequestId);
-  const handlers = await initPromise;
-  const records = event.Records || [];
-  const grouped = groupBySource(records);
-
-  await Promise.all(Object.entries(grouped).map(async ([arn, subRecords]) => {
-    const streamHandlers = handlers[arn];
-    if (streamHandlers !== undefined && streamHandlers.length > 0) {
-      log.debug("found " + streamHandlers.length + " handler(s) for " + arn, { comp: "SideEffectRuntime" });
-      const correlationId = extractMetaField(subRecords, "correlationId");
-      const causationId = extractMetaField(subRecords, "causationId");
-      const timestamp = extractSentTimestamp(subRecords);
-      const retryCount = extractRetryCount(subRecords);
-      await Promise.all(streamHandlers.map(({ handler: h, comp, plugin }) =>
-        runEffect(h({ Records: subRecords }, context), {
-          correlationId,
-          causationId,
-          comp,
-          plugin,
-          timestamp,
-          retryCount,
-        })
-      ));
-    } else {
-      log.warn("no handler found: " + arn, { comp: "SideEffectRuntime" });
-    }
-  }));
-
-  return "";
-}
+export const handler = StreamOps.makeRoutedHandler("SideEffectRuntime", buildAllHandlers());

package/src/adapter/Runtime/SideEffectEntryPoint_Ops.res

@@ -0,0 +1,71 @@
+// Typed cold-start core for the SideEffectHandler Lambda entry point.
+//
+// The "typed core, thin shell" split (docs/plans/minimize-lambda-entrypoint-mjs-shell.md):
+// SideEffectEntryPoint.mjs keeps only the untyped seam — the dynamic `import()`
+// of the side-effect modules named in HANDLER_CONFIG and the
+// SideEffectHandler_Callback.Make functor application consuming them.
+// HANDLER_CONFIG parsing and handler registration live here, fully
+// type-checked; the routed dispatch boundary is shared with the other
+// stream-routed entry points in StreamRoutedEntryPoint_Ops.
+
+type handlerEntry = {
+  sourceUrn: string,
+  sideEffectModules: array<string>,
+  // Resolved at deploy time and baked into HANDLER_CONFIG
+  // (SideEffectHandlerRuntime_Builder_Single) — the shell has only module paths
+  // to identify a handler by.
+  comp: option<string>,
+  plugin: option<string>,
+}
+
+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 => {
+    sourceUrn: h->strOf("sourceUrn")->Option.getOr(""),
+    sideEffectModules: h
+    ->Dict.get("sideEffectModules")
+    ->Option.flatMap(JSON.Decode.array)
+    ->Option.getOr([])
+    ->Array.filterMap(JSON.Decode.string),
+    comp: h->strOf("comp"),
+    plugin: h->strOf("plugin"),
+  })
+
+let parseHandlerConfig = (rawJson: string): array<handlerEntry> =>
+  rawJson == ""
+    ? []
+    : rawJson
+      ->JSON.parseOrThrow
+      ->JSON.Decode.object
+      ->Option.flatMap(obj => obj->Dict.get("handlers"))
+      ->Option.flatMap(JSON.Decode.array)
+      ->Option.getOr([])
+      ->Array.filterMap(decodeEntry)
+
+// Side effects are fire-and-forget consumers with no query access in the
+// bundled handler — same restriction as the former shell's no-op stub.
+let noopQueryEngine: Reventless.QueryEngine.operations = {
+  scan: async (~readModelName as _, ~filterConfigs as _, ~limit as _) => [],
+  query: async (
+    ~readModelName as _,
+    ~key as _=?,
+    ~id as _,
+    ~subIdConfig as _=?,
+    ~filterConfigs as _=?,
+    ~ascending as _=?,
+    ~limit as _=?,
+  ) => [],
+}
+
+let makeRegisteredHandler = (
+  entry: handlerEntry,
+  handleJsonEvents: ReventlessCore.EventCollector.jsonEventsHandler,
+): StreamRoutedEntryPoint_Ops.registeredHandler => {
+  handler: StreamRoutedEntryPoint_Ops.toStreamHandler(handleJsonEvents),
+  comp: ?entry.comp,
+  plugin: ?entry.plugin,
+}

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

@@ -0,0 +1,57 @@
+// 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 StreamRoutedEntryPoint_Ops$ReventlessAws from "./StreamRoutedEntryPoint_Ops.res.mjs";
+
+function strOf(obj, key) {
+  return Stdlib_Option.flatMap(obj[key], Stdlib_JSON.Decode.string);
+}
+
+function decodeEntry(json) {
+  return Stdlib_Option.map(Stdlib_JSON.Decode.object(json), h => ({
+    sourceUrn: Stdlib_Option.getOr(strOf(h, "sourceUrn"), ""),
+    sideEffectModules: Stdlib_Array.filterMap(Stdlib_Option.getOr(Stdlib_Option.flatMap(h["sideEffectModules"], Stdlib_JSON.Decode.array), []), Stdlib_JSON.Decode.string),
+    comp: strOf(h, "comp"),
+    plugin: strOf(h, "plugin")
+  }));
+}
+
+function parseHandlerConfig(rawJson) {
+  if (rawJson === "") {
+    return [];
+  } else {
+    return Stdlib_Array.filterMap(Stdlib_Option.getOr(Stdlib_Option.flatMap(Stdlib_Option.flatMap(Stdlib_JSON.Decode.object(JSON.parse(rawJson)), obj => obj["handlers"]), Stdlib_JSON.Decode.array), []), decodeEntry);
+  }
+}
+
+async function noopQueryEngine_scan(param, param$1, param$2) {
+  return [];
+}
+
+async function noopQueryEngine_query(param, param$1, param$2, param$3, param$4, param$5, param$6) {
+  return [];
+}
+
+let noopQueryEngine = {
+  scan: noopQueryEngine_scan,
+  query: noopQueryEngine_query
+};
+
+function makeRegisteredHandler(entry, handleJsonEvents) {
+  return {
+    handler: StreamRoutedEntryPoint_Ops$ReventlessAws.toStreamHandler(handleJsonEvents),
+    comp: entry.comp,
+    plugin: entry.plugin
+  };
+}
+
+export {
+  strOf,
+  decodeEntry,
+  parseHandlerConfig,
+  noopQueryEngine,
+  makeRegisteredHandler,
+}
+/* StreamRoutedEntryPoint_Ops-ReventlessAws Not a pure module */

package/src/adapter/Runtime/StateViewSliceEntryPoint.mjs

@@ -1,177 +1,46 @@
 // StateViewSlice Lambda entry point.
-// At cold start: reads HANDLER_CONFIG, dynamically imports Spec modules,
-// builds projection handler that decodes events and runs Projection.handleAction.
-// Routes DynamoDB Stream events by source URN.
-
-import * as Effect from "effect/Effect";
-import * as Stream from "effect/Stream";
-import { parseJsonOrThrow } from "sury/src/S.res.mjs";
-import {
-  log,
-  runEffect,
-  setRequestId,
-  extractMetaField,
-  extractSentTimestamp,
-  extractRetryCount,
-} from "./HandlerFactoryHelpers.mjs";
-import { handleAction } from "@reventlessdev/reventless-core/src/Projection.res.mjs";
-// Typed cold-start core — DynamoDB QueryDb ops, compiler-checked against the
-// framework signatures (see the module header and
-// docs/plans/minimize-lambda-entrypoint-mjs-shell.md).
-import { makeDynamoQueryDbOps } from "./QueryDbEntryPoint_Ops.res.mjs";
-import { opsFor as pgQdbOpsFor } from "@reventlessdev/reventless-aws/src/adapter/QueryDb/QueryDbStorage_Postgres_Runtime.res.mjs";
-import { withLiveUpdates } from "./StateTopicPublish.mjs";
-import { handleStreamEvent } from "@reventlessdev/reventless-aws/src/adapter/EventCollector/EventCollectorChannel_DynamoDbStream_Runtime.res.mjs";
+// At cold start: reads HANDLER_CONFIG, dynamically imports Spec/Projection
+// modules, builds a projection handler per slice, and routes stream events by
+// source URN.
+//
+// Thin untyped shell ("typed core, thin shell" —
+// docs/plans/minimize-lambda-entrypoint-mjs-shell.md): this file owns ONLY the
+// inherently-untyped seam — the dynamic `import()` of spec/projection modules
+// named in HANDLER_CONFIG and the reads of their exports. Everything else
+// (HANDLER_CONFIG parsing incl. the compact-v2 expansion, the QueryDb operation
+// assembly incl. the Postgres / live-update branch, the projection stream
+// pipeline, the routed dispatch boundary) lives type-checked in
+// StateViewSliceEntryPoint_Ops.res / ProjectionEntryPoint_Ops.res /
+// StreamRoutedEntryPoint_Ops.res.
+
+import * as StreamOps from "./StreamRoutedEntryPoint_Ops.res.mjs";
+import * as Ops from "./StateViewSliceEntryPoint_Ops.res.mjs";
 
 const dynamicImport = (specifier) => import('/var/task/node_modules/' + specifier);
 
-// One Lambda hosts every state-view slice of a plugin, so each handler carries
-// the comp of the slice it projects — matching the `StateViewSlice(<name>)`
-// shape the rest of the framework logs under.
-const stateViewComp = (sliceName) => `StateViewSlice(${sliceName})`;
-
-function groupBySource(records) {
-  const dict = {};
-  records.forEach(record => {
-    const arn = record.eventSourceARN;
-    const existing = dict[arn] || [];
-    dict[arn] = existing.concat([record]);
-  });
-  return dict;
-}
-
-// `pgConnection`, when present, selects the Postgres QueryDb runtime for this
-// slice's view table (`queryDbTableName` is then the slice spec name, the shared
-// `qdb_<name>` discriminator). Absent → the DynamoDB path is byte-identical.
-export function buildJsonEventsHandler(specModule, projectionModule, queryDbTableName, pgConnection, stateTopicName) {
-  let queryDbOps;
-  if (pgConnection) {
-    const indexes = (specModule.config && specModule.config.indexes) || [];
-    const subIdField = specModule.subIdConfig ? specModule.subIdConfig.subIdField : undefined;
-    const pgOps = pgQdbOpsFor(pgConnection, queryDbTableName, indexes, subIdField);
-    // B3.3: subscription-enabled (Stream) Postgres view slice → publish a
-    // live-update descriptor after save/delete. `stateTopicName` + APPSYNC_ENDPOINT
-    // gate it; absent → withLiveUpdates passes pgOps through. The view slice's id
-    // is the save's first arg (no id injection), so no wrap-ordering concern.
-    queryDbOps = withLiveUpdates(pgOps, {
-      endpoint: process.env.APPSYNC_ENDPOINT,
-      region: process.env.AWS_REGION,
-      topicName: stateTopicName,
-      subIdField,
-    });
-  } else {
-    queryDbOps = makeDynamoQueryDbOps(queryDbTableName);
-  }
-  // Spec module exports `consumedEventSchema`; the `project` function lives in
-  // the sibling projection module (`<Name>_Projection.res`).
-  const eventSchema = specModule.consumedEventSchema;
-  const project = projectionModule.project;
-
-  return stream => Stream.runForEach(
-    Stream.flatMap(
-      Stream.mapEffect(stream, json => Effect.sync(() => {
-        try {
-          // Events arrive as `{id, meta, recordedAt, event}` envelopes
-          // (Util_DynamoDbStream_Runtime.buildJsonEvent' / PgChangeFeedRelay).
-          // Surface `meta` + `recordedAt` to the projection as the `consumed`
-          // envelope; `recordedAt` defaults to "" if a producer omitted it.
-          const eventJson = json.event != null ? json.event : json;
-          const meta = json.meta;
-          const recordedAt = json.recordedAt != null ? json.recordedAt : "";
-          return project({ event: parseJsonOrThrow(eventJson, eventSchema), meta, recordedAt });
-        } catch (exn) {
-          log.error("failed to decode event", { comp: "StateViewSliceRuntime", detail: exn && exn.message ? exn.message : String(exn) });
-          return [];
-        }
-      })),
-      actions => Stream.fromIterable(actions)
-    ),
-    action => Effect.map(
-      // Thread the slice's `subIdConfig` (generated from `@subId`) so sub-id-dependent
-      // actions like `UpdateMultiState` can resolve the sort key. Dropping it here made
-      // every such action hit the `MissingSubIdConfig` guard and silently write nothing,
-      // while the test-harness callback path (which threads it) stayed green. `undefined`
-      // for slices without an `@subId` is correct — those never emit sub-id actions.
-      // First positional arg is the compiled `~comp=` optional (attribution
-      // for Projection.handleAction's debug-lazy action log) — the slice's
-      // spec name. Compiled shape: (comp, action, operations, subIdConfig).
-      Effect.promise(() => handleAction(specModule.name, action, queryDbOps, specModule.subIdConfig)),
-      _ => {}
-    )
-  );
-}
-
-// HANDLER_CONFIG is emitted compact (StateViewSliceRuntime_Builder_Single) to
-// stay under AWS Lambda's 4KB env-var limit: a shared module-path `base` and a
-// shared `sourceUrn` are hoisted out, and per-handler keys are shortened to
-// s/p/q/u. Expand back to the full {specModule, projectionModule,
-// queryDbTableName, sourceUrn} shape. Legacy full-key entries pass through.
-function expandHandlers(config) {
-  const base = config.base || "";
-  const sharedUrn = config.sourceUrn || "";
-  return (config.handlers || []).map(h => {
-    if (h.specModule !== undefined) return h;
-    return {
-      specModule: base + h.s,
-      projectionModule: base + h.p,
-      queryDbTableName: h.q,
-      sourceUrn: h.u !== undefined ? h.u : sharedUrn,
-      // Shared across a plugin's slices (all follow the platform backend toggle);
-      // hoisted to the top level of the compressed config like base/sourceUrn.
-      pgConnection: config.pgConnection,
-      // B3.3: per-slice AppSync Events channel root (list field name). Present
-      // only for subscription-enabled (Stream) Postgres view slices.
-      stateTopicName: h.t,
-    };
-  });
-}
-
 async function buildAllHandlers() {
-  const configStr = process.env["HANDLER_CONFIG"] || '{"handlers":[]}';
-  const config = JSON.parse(configStr);
   const handlers = {};
-  await Promise.all(expandHandlers(config).map(async h => {
+  const entries = Ops.parseHandlerConfig(process.env["HANDLER_CONFIG"] || "");
+
+  await Promise.all(entries.map(async (entry) => {
     const [specModule, projectionModule] = await Promise.all([
-      dynamicImport(h.specModule),
-      dynamicImport(h.projectionModule),
+      dynamicImport(entry.specModule),
+      dynamicImport(entry.projectionModule),
     ]);
-    const jsonEventsHandler = buildJsonEventsHandler(specModule, projectionModule, h.queryDbTableName, h.pgConnection, h.stateTopicName);
-    const streamHandler = (event, context) => handleStreamEvent(jsonEventsHandler, event, context);
-    const existing = handlers[h.sourceUrn] || [];
-    existing.push({ handler: streamHandler, comp: stateViewComp(specModule.name) });
-    handlers[h.sourceUrn] = existing;
+    StreamOps.addToRegistry(
+      handlers,
+      entry.sourceUrn,
+      Ops.makeRegisteredHandler(entry, {
+        name: specModule.name,
+        consumedEventSchema: specModule.consumedEventSchema,
+        project: projectionModule.project,
+        config: specModule.config,
+        subIdConfig: specModule.subIdConfig,
+      })
+    );
   }));
+
   return handlers;
 }
 
-const initPromise = buildAllHandlers();
-
-export async function handler(event, context) {
-  setRequestId(context?.awsRequestId);
-  const handlers = await initPromise;
-  const records = event.Records || [];
-  const grouped = groupBySource(records);
-
-  await Promise.all(Object.entries(grouped).map(async ([arn, subRecords]) => {
-    const streamHandlers = handlers[arn];
-    if (streamHandlers !== undefined && streamHandlers.length > 0) {
-      log.debug("found " + streamHandlers.length + " handler(s) for " + arn, { comp: "StateViewSliceRuntime" });
-      const correlationId = extractMetaField(subRecords, "correlationId");
-      const causationId = extractMetaField(subRecords, "causationId");
-      const timestamp = extractSentTimestamp(subRecords);
-      const retryCount = extractRetryCount(subRecords);
-      await Promise.all(streamHandlers.map(({ handler: h, comp }) =>
-        runEffect(h({ Records: subRecords }, context), {
-          correlationId,
-          causationId,
-          comp,
-          timestamp,
-          retryCount,
-        })
-      ));
-    } else {
-      log.warn("no handler found: " + arn, { comp: "StateViewSliceRuntime" });
-    }
-  }));
-  return "";
-}
+export const handler = StreamOps.makeRoutedHandler("StateViewSliceRuntime", buildAllHandlers());

package/src/adapter/Runtime/StateViewSliceEntryPoint_Ops.res

@@ -0,0 +1,206 @@
+// Typed cold-start core for the StateViewSlice Lambda entry point.
+//
+// The "typed core, thin shell" split (docs/plans/minimize-lambda-entrypoint-mjs-shell.md):
+// StateViewSliceEntryPoint.mjs keeps only the inherently-untyped seam — the
+// dynamic `import()` of spec/projection modules named in HANDLER_CONFIG and the
+// reads of their exports. HANDLER_CONFIG parsing (including the compact-v2
+// expansion), the QueryDb operation assembly, and the whole projection stream
+// pipeline (envelope decode → sury event parse → project → handleAction) live
+// here, fully type-checked; the QueryDb backend branch is shared with the
+// ReadModel entry point in ProjectionEntryPoint_Ops and the routed dispatch
+// boundary lives in StreamRoutedEntryPoint_Ops.
+
+type handlerEntry = {
+  specModule: string,
+  projectionModule: string,
+  queryDbTableName: string,
+  sourceUrn: string,
+  // B3.3: per-slice AppSync Events channel root (list field name). Present only
+  // for subscription-enabled (Stream) Postgres view slices.
+  stateTopicName: option<string>,
+  pgConnection: option<PgConnection.connectionConfig>,
+}
+
+// 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 pgConnectionOf = (obj: dict<JSON.t>): option<PgConnection.connectionConfig> =>
+  obj
+  ->Dict.get("pgConnection")
+  ->Option.filter(j => j != JSON.Null)
+  ->Option.map(asPgConnection)
+
+// HANDLER_CONFIG is emitted compact (StateViewSliceRuntime_Builder_Single) to
+// stay under AWS Lambda's 4KB env-var limit: a shared module-path `base`, a
+// shared `sourceUrn`, and a shared `pgConnection` are hoisted out (all of a
+// plugin's slices follow the platform backend toggle), and per-handler keys are
+// shortened to s/p/q/u/t. Expand back to the full handlerEntry shape. Legacy
+// full-key entries pass through with their own per-entry fields.
+let parseHandlerConfig = (rawJson: string): array<handlerEntry> =>
+  rawJson == ""
+    ? []
+    : {
+        let obj =
+          rawJson
+          ->JSON.parseOrThrow
+          ->JSON.Decode.object
+          ->Option.getOr(Dict.make())
+        let base = obj->strOf("base")->Option.getOr("")
+        let sharedUrn = obj->strOf("sourceUrn")->Option.getOr("")
+        let sharedPgConnection = obj->pgConnectionOf
+        obj
+        ->Dict.get("handlers")
+        ->Option.flatMap(JSON.Decode.array)
+        ->Option.getOr([])
+        ->Array.filterMap(item =>
+          item
+          ->JSON.Decode.object
+          ->Option.map(h =>
+            switch h->strOf("specModule") {
+            | Some(specModule) => {
+                specModule,
+                projectionModule: h->strOf("projectionModule")->Option.getOr(""),
+                queryDbTableName: h->strOf("queryDbTableName")->Option.getOr(""),
+                sourceUrn: h->strOf("sourceUrn")->Option.getOr(""),
+                stateTopicName: h->strOf("stateTopicName"),
+                pgConnection: h->pgConnectionOf,
+              }
+            | None => {
+                specModule: base ++ h->strOf("s")->Option.getOr(""),
+                projectionModule: base ++ h->strOf("p")->Option.getOr(""),
+                queryDbTableName: h->strOf("q")->Option.getOr(""),
+                sourceUrn: h->strOf("u")->Option.getOr(sharedUrn),
+                stateTopicName: h->strOf("t"),
+                pgConnection: sharedPgConnection,
+              }
+            }
+          )
+        )
+      }
+
+// ── Projection stream pipeline ──────────────────────────────────────────────
+
+// Events arrive as `{id, meta, recordedAt, event}` envelopes
+// (Util_DynamoDbStream_Runtime.buildJsonEvent' / PgChangeFeedRelay). Surface
+// `meta` + `recordedAt` to the projection as the `consumed` envelope;
+// `recordedAt` defaults to "" if a producer omitted it. `meta` is already
+// schema-shaped JSON written by the producer — cast at the documented contract
+// (absent maps to undefined, exactly what the former JS passed through).
+external asMeta: option<JSON.t> => Reventless.Message.meta = "%identity"
+
+type envelope<'event> = {
+  event: JSON.t,
+  meta: Reventless.Message.meta,
+  recordedAt: string,
+}
+
+let decodeEnvelope = (json: JSON.t): envelope<'event> => {
+  let fields = json->JSON.Decode.object
+  {
+    event: switch fields->Option.flatMap(f => f->Dict.get("event")) {
+    | Some(JSON.Null) | None => json
+    | Some(event) => event
+    },
+    meta: fields->Option.flatMap(f => f->Dict.get("meta"))->asMeta,
+    recordedAt: fields
+    ->Option.flatMap(f => f->Dict.get("recordedAt"))
+    ->Option.flatMap(JSON.Decode.string)
+    ->Option.getOr(""),
+  }
+}
+
+let exnMessage = StreamRoutedEntryPoint_Ops.exnMessage
+
+// The typed core of buildJsonEventsHandler: decode each envelope, parse the
+// event against the slice's consumed-event schema, project, and run every
+// resulting action against the view table. A decode failure logs and yields no
+// actions (the batch continues — at-least-once delivery would otherwise wedge
+// the whole source on one malformed record).
+let makeJsonEventsHandler = (
+  ~sliceName: string,
+  ~eventSchema: S.t<'event>,
+  ~project: Reventless.StateViewSlice.consumed<'event> => array<
+    Reventless.Projection.action<string, JSON.t>,
+  >,
+  ~queryDbOps: ReventlessCore.QueryDb_Adapter.operations,
+  ~subIdConfig: option<Reventless.ReadModel.subIdConfig<JSON.t>>,
+): ReventlessCore.EventCollector.jsonEventsHandler =>
+  stream =>
+    stream
+    ->Stream.mapEffect(json =>
+      Effect.sync(() =>
+        try {
+          let {event, meta, recordedAt} = decodeEnvelope(json)
+          project({event: event->S.parseJsonOrThrow(eventSchema), meta, recordedAt})
+        } catch {
+        | exn =>
+          StreamRoutedEntryPoint_Ops.logError(
+            "failed to decode event",
+            {comp: "StateViewSliceRuntime", detail: exnMessage(exn)},
+          )
+          []
+        }
+      )
+    )
+    ->Stream.flatMap(actions => Stream.fromIterable(actions))
+    ->Stream.runForEach(action =>
+      // Thread the slice's `subIdConfig` (generated from `@subId`) so
+      // sub-id-dependent actions like `UpdateMultiState` can resolve the sort
+      // key. Dropping it here made every such action hit the
+      // `MissingSubIdConfig` guard and silently write nothing, while the
+      // test-harness callback path (which threads it) stayed green. `None` for
+      // slices without an `@subId` is correct — those never emit sub-id
+      // actions. `~comp` is the slice's spec name — attribution for
+      // Projection.handleAction's debug-lazy action log.
+      Effect.promise(() =>
+        ReventlessCore.Projection.handleAction(~comp=sliceName, action, queryDbOps, subIdConfig)
+      )->Effect.map(_ => ())
+    )
+
+// ── Handler assembly (called by the shell per HANDLER_CONFIG entry) ─────────
+// `sliceModules` types the shell's reads off the two dynamically imported
+// modules: the spec module exports `name` / `consumedEventSchema` / `config` /
+// `subIdConfig`; the `project` function lives in the sibling projection module
+// (`<Name>_Projection.res`).
+
+type sliceModules<'event> = {
+  name: string,
+  consumedEventSchema: S.t<'event>,
+  project: Reventless.StateViewSlice.consumed<'event> => array<
+    Reventless.Projection.action<string, JSON.t>,
+  >,
+  config: option<ProjectionEntryPoint_Ops.specConfig>,
+  subIdConfig: option<Reventless.ReadModel.subIdConfig<JSON.t>>,
+}
+
+let makeRegisteredHandler = (
+  entry: handlerEntry,
+  modules: sliceModules<'event>,
+): StreamRoutedEntryPoint_Ops.registeredHandler => {
+  let queryDbOps = ProjectionEntryPoint_Ops.makeQueryDbOps(
+    ~queryDbTableName=entry.queryDbTableName,
+    ~pgConnection=entry.pgConnection,
+    ~stateTopicName=entry.stateTopicName,
+    ~indexes=ProjectionEntryPoint_Ops.indexesOf(modules.config),
+    ~subIdField=ProjectionEntryPoint_Ops.subIdFieldOf(modules.subIdConfig),
+  )
+  {
+    handler: StreamRoutedEntryPoint_Ops.toStreamHandler(
+      makeJsonEventsHandler(
+        ~sliceName=modules.name,
+        ~eventSchema=modules.consumedEventSchema,
+        ~project=modules.project,
+        ~queryDbOps,
+        ~subIdConfig=modules.subIdConfig,
+      ),
+    ),
+    // Matches the `StateViewSlice(<name>)` shape the rest of the framework
+    // logs under.
+    comp: `StateViewSlice(${modules.name})`,
+  }
+}