@reventlessdev/reventless-aws 3.0.0-alpha.220 → 3.0.0-alpha.221

package/src/util/Util_LogAttribution.res

@@ -0,0 +1,31 @@
+// Deploy-time log attribution baked into HANDLER_CONFIG.
+//
+// The deployed entry points annotate each invocation with `comp` and `plugin`
+// (HandlerFactoryHelpers.runEffect). `comp` a shell can usually derive itself
+// from the spec name it loads; `plugin` it cannot — resolution goes through
+// LogPrefix's component→plugin registry, which `Plugin_Builder.construct`
+// populates at **deploy** time and which is empty inside a Lambda. And the
+// Lambda-name fallback (`derivePluginFromLambdaName`) only works for Lambdas
+// named `<Plugin>Plugin<Suffix>`: it yields nothing for a shared multi-plugin
+// Lambda (`AllAggregatesCmdHandler`, `AllReadModels`) or a per-component one
+// (`<Aggregate>Aggr`) — exactly the cases where the field matters most.
+//
+// So resolve it here, where the registry exists, and ship it in the config.
+// See docs/plans/entrypoint-dispatch-parity-and-latency-fields.md.
+
+/** `,"plugin":"<Name>"` for a HANDLER_CONFIG entry, or `""` when the comp
+    resolves to no plugin (the shell then falls back to the Lambda name). */
+let pluginFragment = (~comp: string): string =>
+  switch ReventlessCore.Logger.resolvePlugin(~comp, ()) {
+  | Some(plugin) => `,"plugin":${plugin->JSON.Encode.string->JSON.stringify}`
+  | None => ""
+  }
+
+/** `,"comp":"<Kind(Name)>"` for a HANDLER_CONFIG entry. For the shells that
+    cannot name the element themselves — a read model or side-effect handler is
+    known to its shell only by module path, while the aggregate/slice shells read
+    the name off the spec they load. */
+let compFragment = (~comp: string): string => `,"comp":${comp->JSON.Encode.string->JSON.stringify}`
+
+/** Both fragments, in the order the entry points expect. */
+let fragments = (~comp: string): string => compFragment(~comp) ++ pluginFragment(~comp)

package/src/util/Util_LogAttribution.res.mjs

@@ -0,0 +1,27 @@
+// Generated by ReScript, PLEASE EDIT WITH CARE
+
+import * as Logger$ReventlessCore from "@reventlessdev/reventless-core/src/util/Logger.res.mjs";
+
+function pluginFragment(comp) {
+  let plugin = Logger$ReventlessCore.resolvePlugin(comp, undefined);
+  if (plugin !== undefined) {
+    return `,"plugin":` + JSON.stringify(plugin);
+  } else {
+    return "";
+  }
+}
+
+function compFragment(comp) {
+  return `,"comp":` + JSON.stringify(comp);
+}
+
+function fragments(comp) {
+  return compFragment(comp) + pluginFragment(comp);
+}
+
+export {
+  pluginFragment,
+  compFragment,
+  fragments,
+}
+/* Logger-ReventlessCore Not a pure module */

package/tests/AWS_TagsTest.res

@@ -0,0 +1,236 @@
+open JestGlobals
+
+// Guards the resource-attribution tag schema. A downstream inventory answers
+// "which model component owns this resource, in what role, at what scope" purely
+// from these keys, so the key set and its namespacing are load-bearing.
+// See docs/plans/resource-attribution-tag-schema.md.
+
+module Attribution = ReventlessCore.ResourceAttribution
+
+// Pulumi.Input.make is %identity, so the tags value is the underlying dict.
+external toDict: Pulumi.Input.t<dict<string>> => dict<string> = "%identity"
+
+let tagsFor = (
+  ~name,
+  ~kind,
+  ~role,
+  ~scope: Attribution.Scope.t=Component,
+  ~component=?,
+  ~plugin=?,
+  ~platform=?,
+) =>
+  AWS_Tags.make(~name, ~kind, ~role, ~scope, ~component?, ~plugin?, ~platform?)->toDict
+
+describe("AWS_Tags — key set", () => {
+  testSync("emits every reventless: fact exactly once, plus the bare Name", () => {
+    let keys =
+      tagsFor(
+        ~name="ProductsQueryDb",
+        ~kind=ReventlessCore.ComponentType.ReadModel,
+        ~role=QueryDb,
+        ~plugin="Catalog",
+        ~platform="online-shop",
+      )
+      ->Dict.keysToArray
+      ->Array.toSorted(String.compare)
+    expect(keys)->toEqual([
+      "Name",
+      "reventless:component",
+      "reventless:environment",
+      "reventless:kind",
+      "reventless:platform",
+      "reventless:plugin",
+      "reventless:role",
+      "reventless:scope",
+    ])
+  })
+
+  testSync("the dropped bare duplicates stay dropped", () => {
+    // `Type` and `Plugin` were exact duplicates of reventless:kind / :plugin, and
+    // `Environment` was a framework fact wearing an un-namespaced name. One
+    // authoritative name per fact — `Name` is the sole bare key, because the AWS
+    // console reads that literal spelling for its resource-name column.
+    let tags = tagsFor(~name="Products", ~kind=ReventlessCore.ComponentType.ReadModel, ~role=QueryDb)
+    expect(tags->Dict.get("Type"))->toEqual(None)
+    expect(tags->Dict.get("Plugin"))->toEqual(None)
+    expect(tags->Dict.get("Environment"))->toEqual(None)
+    expect(tags->Dict.get("Name"))->toEqual(Some("Products"))
+  })
+})
+
+describe("AWS_Tags — role and kind are independent facts", () => {
+  testSync("one component kind spans several piece roles", () => {
+    let kind = ReventlessCore.ComponentType.Aggregate
+    let eventLog = tagsFor(~name="OrderEventLog", ~kind, ~role=EventLog)
+    let commandTopic = tagsFor(~name="OrderCmdTopic", ~kind, ~role=CommandTopic)
+    expect(eventLog->Dict.get("reventless:kind"))->toEqual(Some("Aggregate"))
+    expect(commandTopic->Dict.get("reventless:kind"))->toEqual(Some("Aggregate"))
+    expect(eventLog->Dict.get("reventless:role"))->toEqual(Some("EventLog"))
+    expect(commandTopic->Dict.get("reventless:role"))->toEqual(Some("CommandTopic"))
+  })
+
+  testSync("one piece role spans several component kinds — the Lambda mis-tag", () => {
+    // Regression guard for the defect this schema exists to fix: every runtime
+    // Lambda used to report kind=role=CommandTopic regardless of what it ran.
+    let aggregate = tagsFor(
+      ~name="AllAggregatesCmdHandler",
+      ~kind=ReventlessCore.ComponentType.Aggregate,
+      ~role=Runtime,
+    )
+    let projection = tagsFor(
+      ~name="ProductsProjection",
+      ~kind=ReventlessCore.ComponentType.StateViewSlice,
+      ~role=Runtime,
+    )
+    expect(aggregate->Dict.get("reventless:role"))->toEqual(Some("Runtime"))
+    expect(projection->Dict.get("reventless:role"))->toEqual(Some("Runtime"))
+    expect(aggregate->Dict.get("reventless:kind"))->toEqual(Some("Aggregate"))
+    expect(projection->Dict.get("reventless:kind"))->toEqual(Some("StateViewSlice"))
+    // …and neither reports the old hardcoded lie.
+    expect(aggregate->Dict.get("reventless:kind") == Some("CommandTopic"))->toBe(false)
+  })
+})
+
+describe("AWS_Tags — owner overrides the piece adapter's own kind", () => {
+  // The piece adapters pass their OWN ComponentType as ~kind, which names the
+  // piece and so collapses onto ~role. A QueryDb is instantiated by six different
+  // component kinds, so without the owner a reader cannot tell a ReadModel's
+  // table from a StateViewSlice's. See docs/plans/resource-attribution-owner-kind.md.
+  let queryDbTagsFor = (~owner=?) =>
+    AWS_Tags.make(
+      ~name="ProductsQueryDb",
+      ~kind=ReventlessCore.ComponentType.QueryDb,
+      ~role=QueryDb,
+      ~owner?,
+    )->toDict
+
+  testSync("without an owner, kind still names the piece", () => {
+    let tags = queryDbTagsFor()
+    expect(tags->Dict.get("reventless:kind"))->toEqual(Some("QueryDB"))
+    expect(tags->Dict.get("reventless:role"))->toEqual(Some("QueryDb"))
+  })
+
+  testSync("two QueryDb tables under different owners differ in kind", () => {
+    let readModel = queryDbTagsFor(
+      ~owner={kind: ReventlessCore.ComponentType.ReadModel, name: "Products"},
+    )
+    let stateView = queryDbTagsFor(
+      ~owner={kind: ReventlessCore.ComponentType.StateViewSlice, name: "ProductAvailability"},
+    )
+    expect(readModel->Dict.get("reventless:kind"))->toEqual(Some("ReadModel"))
+    expect(stateView->Dict.get("reventless:kind"))->toEqual(Some("StateViewSlice"))
+    // …while both still report the same piece role.
+    expect(readModel->Dict.get("reventless:role"))->toEqual(Some("QueryDb"))
+    expect(stateView->Dict.get("reventless:role"))->toEqual(Some("QueryDb"))
+  })
+
+  testSync("the owner also supplies the component stem, not the resource name", () => {
+    let tags = queryDbTagsFor(
+      ~owner={kind: ReventlessCore.ComponentType.ReadModel, name: "Products"},
+    )
+    expect(tags->Dict.get("Name"))->toEqual(Some("ProductsQueryDb"))
+    expect(tags->Dict.get("reventless:component"))->toEqual(Some("Products"))
+  })
+
+  testSync("a Plugin-kinded owner attributes substrate to the plugin", () => {
+    // A plugin IS a model element, so shared substrate is owned by it rather than
+    // by nothing. The owner implies plugin scope even though the piece adapter
+    // passed no ~scope, and it names the plugin.
+    let tags =
+      AWS_Tags.make(
+        ~name="OrderingDcbEventTopic",
+        ~kind=ReventlessCore.ComponentType.EventTopic,
+        ~role=EventTopic,
+        ~owner={kind: ReventlessCore.ComponentType.Plugin, name: "Ordering"},
+      )->toDict
+    expect(tags->Dict.get("reventless:kind"))->toEqual(Some("Plugin"))
+    expect(tags->Dict.get("reventless:scope"))->toEqual(Some("plugin"))
+    expect(tags->Dict.get("reventless:plugin"))->toEqual(Some("Ordering"))
+    expect(tags->Dict.get("reventless:component"))->toEqual(Some(""))
+    // …and the piece it plays is still legible.
+    expect(tags->Dict.get("reventless:role"))->toEqual(Some("EventTopic"))
+  })
+
+  testSync("an owner does not leak a component onto plugin substrate", () => {
+    let tags =
+      AWS_Tags.make(
+        ~name="OrderingDcbEventLog",
+        ~kind=ReventlessCore.ComponentType.DcbEventLog,
+        ~role=DcbEventLog,
+        ~scope=Plugin,
+        ~owner={kind: ReventlessCore.ComponentType.Aggregate, name: "Order"},
+      )->toDict
+    expect(tags->Dict.get("reventless:component"))->toEqual(Some(""))
+  })
+})
+
+describe("AWS_Tags — scope", () => {
+  testSync("component scope names the component, defaulting to the resource name", () => {
+    let tags = tagsFor(~name="Products", ~kind=ReventlessCore.ComponentType.ReadModel, ~role=QueryDb)
+    expect(tags->Dict.get("reventless:scope"))->toEqual(Some("component"))
+    expect(tags->Dict.get("reventless:component"))->toEqual(Some("Products"))
+  })
+
+  testSync("an explicit component stem survives a suffixed resource name", () => {
+    let tags = tagsFor(
+      ~name="ProductsStateTopic",
+      ~kind=ReventlessCore.ComponentType.ReadModel,
+      ~role=StateTopic,
+      ~component="Products",
+    )
+    expect(tags->Dict.get("Name"))->toEqual(Some("ProductsStateTopic"))
+    expect(tags->Dict.get("reventless:component"))->toEqual(Some("Products"))
+  })
+
+  testSync("plugin substrate carries no component, but keeps its plugin", () => {
+    let tags = tagsFor(
+      ~name="OrderingDcbEventLog",
+      ~kind=ReventlessCore.ComponentType.DcbEventLog,
+      ~role=DcbEventLog,
+      ~scope=Plugin,
+      ~plugin="Ordering",
+    )
+    expect(tags->Dict.get("reventless:scope"))->toEqual(Some("plugin"))
+    expect(tags->Dict.get("reventless:component"))->toEqual(Some(""))
+    expect(tags->Dict.get("reventless:plugin"))->toEqual(Some("Ordering"))
+  })
+
+  testSync("platform substrate carries neither component nor plugin", () => {
+    let tags = tagsFor(
+      ~name="UIFragmentsLambda",
+      ~kind=ReventlessCore.ComponentType.ReadModel,
+      ~role=Runtime,
+      ~scope=Platform,
+      ~plugin="Ordering",
+      ~platform="online-shop",
+    )
+    expect(tags->Dict.get("reventless:scope"))->toEqual(Some("platform"))
+    expect(tags->Dict.get("reventless:component"))->toEqual(Some(""))
+    expect(tags->Dict.get("reventless:plugin"))->toEqual(Some(""))
+    expect(tags->Dict.get("reventless:platform"))->toEqual(Some("online-shop"))
+  })
+})
+
+describe("AWS_Tags — plugin attribution", () => {
+  testSync("falls back to the ambient plugin published by Plugin_Builder", () => {
+    // Adapters sit far below the builder that knows the plugin name, so the
+    // ambient context is how a DynamoDB table learns it belongs to Ordering.
+    let previous = Attribution.enter(~platform="online-shop", ~plugin="Ordering")
+    let tags = tagsFor(~name="OrderEventLog", ~kind=ReventlessCore.ComponentType.Aggregate, ~role=EventLog)
+    Attribution.restore(previous)
+    expect(tags->Dict.get("reventless:plugin"))->toEqual(Some("Ordering"))
+    expect(tags->Dict.get("reventless:platform"))->toEqual(Some("online-shop"))
+  })
+
+  testSync("an explicit plugin beats the ambient one", () => {
+    let previous = Attribution.enter(~platform="online-shop", ~plugin="Ordering")
+    let tags = tagsFor(
+      ~name="CatalogTable",
+      ~kind=ReventlessCore.ComponentType.ReadModel,
+      ~role=QueryDb,
+      ~plugin="Catalog",
+    )
+    Attribution.restore(previous)
+    expect(tags->Dict.get("reventless:plugin"))->toEqual(Some("Catalog"))
+  })
+})

package/tests/AWS_TagsTest.res.mjs

@@ -0,0 +1,153 @@
+// Generated by ReScript, PLEASE EDIT WITH CARE
+
+import * as Primitive_object from "@rescript/runtime/lib/es6/Primitive_object.js";
+import * as Primitive_string from "@rescript/runtime/lib/es6/Primitive_string.js";
+import * as AWS_Tags$ReventlessAws from "../src/adapter/AWS_Tags.res.mjs";
+import * as ResourceAttribution$ReventlessCore from "@reventlessdev/reventless-core/src/ResourceAttribution.res.mjs";
+
+function tagsFor(name, kind, role, scopeOpt, component, plugin, platform) {
+  let scope = scopeOpt !== undefined ? scopeOpt : "Component";
+  return AWS_Tags$ReventlessAws.make(name, kind, role, scope, component, undefined, plugin, platform);
+}
+
+globalThis.describe("AWS_Tags — key set", () => {
+  globalThis.test("emits every reventless: fact exactly once, plus the bare Name", () => {
+    let keys = Object.keys(tagsFor("ProductsQueryDb", "ReadModel", "QueryDb", undefined, undefined, "Catalog", "online-shop")).toSorted(Primitive_string.compare);
+    globalThis.expect(keys).toEqual([
+      "Name",
+      "reventless:component",
+      "reventless:environment",
+      "reventless:kind",
+      "reventless:platform",
+      "reventless:plugin",
+      "reventless:role",
+      "reventless:scope"
+    ]);
+  });
+  globalThis.test("the dropped bare duplicates stay dropped", () => {
+    let tags = tagsFor("Products", "ReadModel", "QueryDb", undefined, undefined, undefined, undefined);
+    globalThis.expect(tags["Type"]).toEqual(undefined);
+    globalThis.expect(tags["Plugin"]).toEqual(undefined);
+    globalThis.expect(tags["Environment"]).toEqual(undefined);
+    globalThis.expect(tags["Name"]).toEqual("Products");
+  });
+});
+
+globalThis.describe("AWS_Tags — role and kind are independent facts", () => {
+  globalThis.test("one component kind spans several piece roles", () => {
+    let eventLog = tagsFor("OrderEventLog", "Aggregate", "EventLog", undefined, undefined, undefined, undefined);
+    let commandTopic = tagsFor("OrderCmdTopic", "Aggregate", "CommandTopic", undefined, undefined, undefined, undefined);
+    globalThis.expect(eventLog["reventless:kind"]).toEqual("Aggregate");
+    globalThis.expect(commandTopic["reventless:kind"]).toEqual("Aggregate");
+    globalThis.expect(eventLog["reventless:role"]).toEqual("EventLog");
+    globalThis.expect(commandTopic["reventless:role"]).toEqual("CommandTopic");
+  });
+  globalThis.test("one piece role spans several component kinds — the Lambda mis-tag", () => {
+    let aggregate = tagsFor("AllAggregatesCmdHandler", "Aggregate", "Runtime", undefined, undefined, undefined, undefined);
+    let projection = tagsFor("ProductsProjection", "StateViewSlice", "Runtime", undefined, undefined, undefined, undefined);
+    globalThis.expect(aggregate["reventless:role"]).toEqual("Runtime");
+    globalThis.expect(projection["reventless:role"]).toEqual("Runtime");
+    globalThis.expect(aggregate["reventless:kind"]).toEqual("Aggregate");
+    globalThis.expect(projection["reventless:kind"]).toEqual("StateViewSlice");
+    globalThis.expect(Primitive_object.equal(aggregate["reventless:kind"], "CommandTopic")).toBe(false);
+  });
+});
+
+globalThis.describe("AWS_Tags — owner overrides the piece adapter's own kind", () => {
+  let queryDbTagsFor = owner => AWS_Tags$ReventlessAws.make("ProductsQueryDb", "QueryDb", "QueryDb", undefined, undefined, owner, undefined, undefined);
+  globalThis.test("without an owner, kind still names the piece", () => {
+    let tags = queryDbTagsFor(undefined);
+    globalThis.expect(tags["reventless:kind"]).toEqual("QueryDB");
+    globalThis.expect(tags["reventless:role"]).toEqual("QueryDb");
+  });
+  globalThis.test("two QueryDb tables under different owners differ in kind", () => {
+    let readModel = queryDbTagsFor({
+      kind: "ReadModel",
+      name: "Products"
+    });
+    let stateView = queryDbTagsFor({
+      kind: "StateViewSlice",
+      name: "ProductAvailability"
+    });
+    globalThis.expect(readModel["reventless:kind"]).toEqual("ReadModel");
+    globalThis.expect(stateView["reventless:kind"]).toEqual("StateViewSlice");
+    globalThis.expect(readModel["reventless:role"]).toEqual("QueryDb");
+    globalThis.expect(stateView["reventless:role"]).toEqual("QueryDb");
+  });
+  globalThis.test("the owner also supplies the component stem, not the resource name", () => {
+    let tags = queryDbTagsFor({
+      kind: "ReadModel",
+      name: "Products"
+    });
+    globalThis.expect(tags["Name"]).toEqual("ProductsQueryDb");
+    globalThis.expect(tags["reventless:component"]).toEqual("Products");
+  });
+  globalThis.test("a Plugin-kinded owner attributes substrate to the plugin", () => {
+    let tags = AWS_Tags$ReventlessAws.make("OrderingDcbEventTopic", "EventTopic", "EventTopic", undefined, undefined, {
+      kind: "Plugin",
+      name: "Ordering"
+    }, undefined, undefined);
+    globalThis.expect(tags["reventless:kind"]).toEqual("Plugin");
+    globalThis.expect(tags["reventless:scope"]).toEqual("plugin");
+    globalThis.expect(tags["reventless:plugin"]).toEqual("Ordering");
+    globalThis.expect(tags["reventless:component"]).toEqual("");
+    globalThis.expect(tags["reventless:role"]).toEqual("EventTopic");
+  });
+  globalThis.test("an owner does not leak a component onto plugin substrate", () => {
+    let tags = AWS_Tags$ReventlessAws.make("OrderingDcbEventLog", "DcbEventLog", "DcbEventLog", "Plugin", undefined, {
+      kind: "Aggregate",
+      name: "Order"
+    }, undefined, undefined);
+    globalThis.expect(tags["reventless:component"]).toEqual("");
+  });
+});
+
+globalThis.describe("AWS_Tags — scope", () => {
+  globalThis.test("component scope names the component, defaulting to the resource name", () => {
+    let tags = tagsFor("Products", "ReadModel", "QueryDb", undefined, undefined, undefined, undefined);
+    globalThis.expect(tags["reventless:scope"]).toEqual("component");
+    globalThis.expect(tags["reventless:component"]).toEqual("Products");
+  });
+  globalThis.test("an explicit component stem survives a suffixed resource name", () => {
+    let tags = tagsFor("ProductsStateTopic", "ReadModel", "StateTopic", undefined, "Products", undefined, undefined);
+    globalThis.expect(tags["Name"]).toEqual("ProductsStateTopic");
+    globalThis.expect(tags["reventless:component"]).toEqual("Products");
+  });
+  globalThis.test("plugin substrate carries no component, but keeps its plugin", () => {
+    let tags = tagsFor("OrderingDcbEventLog", "DcbEventLog", "DcbEventLog", "Plugin", undefined, "Ordering", undefined);
+    globalThis.expect(tags["reventless:scope"]).toEqual("plugin");
+    globalThis.expect(tags["reventless:component"]).toEqual("");
+    globalThis.expect(tags["reventless:plugin"]).toEqual("Ordering");
+  });
+  globalThis.test("platform substrate carries neither component nor plugin", () => {
+    let tags = tagsFor("UIFragmentsLambda", "ReadModel", "Runtime", "Platform", undefined, "Ordering", "online-shop");
+    globalThis.expect(tags["reventless:scope"]).toEqual("platform");
+    globalThis.expect(tags["reventless:component"]).toEqual("");
+    globalThis.expect(tags["reventless:plugin"]).toEqual("");
+    globalThis.expect(tags["reventless:platform"]).toEqual("online-shop");
+  });
+});
+
+globalThis.describe("AWS_Tags — plugin attribution", () => {
+  globalThis.test("falls back to the ambient plugin published by Plugin_Builder", () => {
+    let previous = ResourceAttribution$ReventlessCore.enter("online-shop", "Ordering");
+    let tags = tagsFor("OrderEventLog", "Aggregate", "EventLog", undefined, undefined, undefined, undefined);
+    ResourceAttribution$ReventlessCore.restore(previous);
+    globalThis.expect(tags["reventless:plugin"]).toEqual("Ordering");
+    globalThis.expect(tags["reventless:platform"]).toEqual("online-shop");
+  });
+  globalThis.test("an explicit plugin beats the ambient one", () => {
+    let previous = ResourceAttribution$ReventlessCore.enter("online-shop", "Ordering");
+    let tags = tagsFor("CatalogTable", "ReadModel", "QueryDb", undefined, undefined, "Catalog", undefined);
+    ResourceAttribution$ReventlessCore.restore(previous);
+    globalThis.expect(tags["reventless:plugin"]).toEqual("Catalog");
+  });
+});
+
+let Attribution;
+
+export {
+  Attribution,
+  tagsFor,
+}
+/*  Not a pure module */

package/tests/HandlerFactoryDispatchTest.res

@@ -0,0 +1,190 @@
+// Regression guard for the deployed entry points' dispatch boundary.
+//
+// `HandlerFactoryHelpers.mjs` is the single place where every Lambda invocation
+// gets its log annotations and its `RequestContext` — the AWS counterpart of
+// ReventlessCore.Runtime.annotateInvocation, which does not run in a Lambda (the
+// runtime builders take `~handler as _` and deploy the .mjs shell instead). Two
+// things here are checkable only from JS and break silently otherwise:
+//
+//   1. `RequestContext.fromOptions` is called across the ReScript/JS seam. A
+//      labelled-argument constructor compiles to positional arguments, so an
+//      inserted field would silently shift every value; `fromOptions` takes one
+//      options object precisely to avoid that, and this test fails if the shell
+//      and the record ever disagree.
+//   2. The transport extractors read two different record shapes — SQS (`body`
+//      envelope + `attributes`) and DynamoDB streams (flat top-level meta
+//      attributes on `NewImage` + `ApproximateCreationDateTime` in *seconds*).
+//
+// See docs/plans/entrypoint-dispatch-parity-and-latency-fields.md.
+
+open JestGlobals
+
+// ─── The shell under test ───────────────────────────────────────────────────
+
+type dispatchOptions = {
+  correlationId?: string,
+  causationId?: string,
+  comp?: string,
+  plugin?: string,
+  timestamp?: float,
+  retryCount?: int,
+}
+
+@module("@reventlessdev/reventless-aws/src/adapter/Runtime/HandlerFactoryHelpers.mjs")
+external runEffect: (Effect.t<'a, 'e, 'r>, dispatchOptions) => promise<'a> = "runEffect"
+
+@module("@reventlessdev/reventless-aws/src/adapter/Runtime/HandlerFactoryHelpers.mjs")
+external setRequestId: string => unit = "setRequestId"
+
+@module("@reventlessdev/reventless-aws/src/adapter/Runtime/HandlerFactoryHelpers.mjs")
+external extractMetaField: (array<'record>, string) => option<string> = "extractMetaField"
+
+@module("@reventlessdev/reventless-aws/src/adapter/Runtime/HandlerFactoryHelpers.mjs")
+external extractSentTimestamp: array<'record> => option<float> = "extractSentTimestamp"
+
+@module("@reventlessdev/reventless-aws/src/adapter/Runtime/HandlerFactoryHelpers.mjs")
+external extractRetryCount: array<'record> => int = "extractRetryCount"
+
+// ─── Record fixtures, typed rather than cast ────────────────────────────────
+
+type sqsAttributes = {
+  @as("SentTimestamp") sentTimestamp: string,
+  @as("ApproximateReceiveCount") approximateReceiveCount: string,
+}
+type sqsRecord = {body: string, attributes: sqsAttributes}
+type bodyOnlyRecord = {body: string}
+
+type streamAttribute = {@as("S") s: string}
+type streamImage = {correlationId: streamAttribute, causationId: streamAttribute}
+type streamPayload = {
+  @as("NewImage") newImage: streamImage,
+  @as("ApproximateCreationDateTime") approximateCreationDateTime: float,
+}
+type streamRecord = {dynamodb: streamPayload}
+
+let sqsRecords = [
+  {
+    body: `{"meta":{"correlationId":"corr-1","causationId":"cause-1"}}`,
+    attributes: {sentTimestamp: "1750000000000", approximateReceiveCount: "3"},
+  },
+]
+
+let streamRecords = [
+  {
+    dynamodb: {
+      newImage: {correlationId: {s: "corr-2"}, causationId: {s: "cause-2"}},
+      approximateCreationDateTime: 1750000001.0,
+    },
+  },
+]
+
+// Read back what the dispatch boundary provided, so the assertions see exactly
+// what an application handler would.
+let capture = (): Effect.t<ReventlessCore.RequestContext.t, string, _> =>
+  Effect.serviceWith(ReventlessCore.RequestContext.tag, ctx => ctx)
+
+describe("entry-point dispatch boundary", () => {
+  describe("SQS records", () => {
+    testSync("reads the envelope out of the body", () => {
+      expect(extractMetaField(sqsRecords, "correlationId"))->Expect.toEqual(Some("corr-1"))
+      expect(extractMetaField(sqsRecords, "causationId"))->Expect.toEqual(Some("cause-1"))
+    })
+
+    testSync("reads SentTimestamp as ms since epoch", () =>
+      expect(extractSentTimestamp(sqsRecords))->Expect.toEqual(Some(1750000000000.0))
+    )
+
+    testSync("reads ApproximateReceiveCount as the delivery attempt", () =>
+      expect(extractRetryCount(sqsRecords))->Expect.toBe(3)
+    )
+  })
+
+  describe("DynamoDB stream records", () => {
+    // EventLog rows store meta keys flat as top-level attributes
+    // (Message.composeMeta rebuilds `meta` from them) — not as a nested map.
+    testSync("reads the envelope off the flat NewImage attributes", () => {
+      expect(extractMetaField(streamRecords, "correlationId"))->Expect.toEqual(Some("corr-2"))
+      expect(extractMetaField(streamRecords, "causationId"))->Expect.toEqual(Some("cause-2"))
+    })
+
+    testSync("converts ApproximateCreationDateTime from seconds to ms", () =>
+      expect(extractSentTimestamp(streamRecords))->Expect.toEqual(Some(1750000001000.0))
+    )
+
+    testSync("reports a first delivery — streams have no receive count", () =>
+      expect(extractRetryCount(streamRecords))->Expect.toBe(1)
+    )
+  })
+
+  describe("absent or malformed input", () => {
+    testSync("an empty batch has no send time", () =>
+      expect(extractSentTimestamp([]))->Expect.toEqual(None)
+    )
+
+    testSync("an unparseable body yields no envelope field", () =>
+      expect(extractMetaField([{body: "not json"}], "correlationId"))->Expect.toEqual(None)
+    )
+  })
+
+  describe("RequestContext provided at dispatch", () => {
+    test("carries the full record, not a bare correlationId literal", async () => {
+      let ctx = await runEffect(
+        capture(),
+        {
+          correlationId: "corr-1",
+          causationId: "cause-1",
+          comp: "AggregateRuntime(Customer)",
+          plugin: "Catalog",
+          timestamp: 1750000000000.0,
+          retryCount: 3,
+        },
+      )
+      expect(ctx.correlationId)->Expect.toBe("corr-1")
+      expect(ctx.causationId)->Expect.toEqual(Some("cause-1"))
+      expect(ctx.component)->Expect.toEqual(Some("AggregateRuntime(Customer)"))
+      expect(ctx.pluginName)->Expect.toEqual(Some("Catalog"))
+      expect(ctx.timestamp)->Expect.toEqual(Some(1750000000000.0))
+      expect(ctx.retryCount)->Expect.toEqual(Some(3))
+    })
+
+    test("fills identity and claims, which the record declares non-optional", async () => {
+      let ctx = await runEffect(capture(), {correlationId: "corr-1"})
+      expect(ctx.identity.userId)->Expect.toBe(Reventless.Identity.anonymous.userId)
+      expect(ctx.claims->Dict.keysToArray)->Expect.toEqual([])
+    })
+
+    test("falls back to a placeholder when no correlationId is on the message", async () => {
+      let ctx = await runEffect(capture(), {comp: "X(Y)"})
+      expect(ctx.correlationId)->Expect.toBe("unknown")
+    })
+  })
+
+  describe("log annotations", () => {
+    // Effect keeps annotations in a HashMap; read it as a dict.
+    let annotations = (): Effect.t<Effect.logAnnotationMap, string, _> => Effect.logAnnotations
+
+    test("promotes comp, causationId and the request id onto every line", async () => {
+      setRequestId("req-abc")
+      let annotated = await runEffect(
+        annotations(),
+        {correlationId: "corr-1", causationId: "cause-1", comp: "EventCollector(Customers)"},
+      )
+      let annotated = annotated->Effect.annotationsToDict
+      expect(annotated->Dict.get("comp"))->Expect.toEqual(Some("EventCollector(Customers)"))
+      expect(annotated->Dict.get("causationId"))->Expect.toEqual(Some("cause-1"))
+      expect(annotated->Dict.get("correlationId"))->Expect.toEqual(Some("corr-1"))
+      expect(annotated->Dict.get("requestId"))->Expect.toEqual(Some("req-abc"))
+    })
+
+    // A constant "1" on every line is noise; its absence is what makes
+    // `filter retryCount > 1` a usable CloudWatch query.
+    test("annotates retryCount only on a redelivery", async () => {
+      let first = await runEffect(annotations(), {correlationId: "c", retryCount: 1})
+      expect(first->Effect.annotationsToDict->Dict.get("retryCount"))->Expect.toEqual(None)
+      let redelivered = await runEffect(annotations(), {correlationId: "c", retryCount: 2})
+      expect(redelivered->Effect.annotationsToDict->Dict.get("retryCount"))->Expect.toEqual(
+        Some("2"),
+      )
+    })
+  })
+})