@reventlessdev/reventless-core 3.0.0-alpha.259 → 3.0.0-alpha.261

package/tests/logger/LogFormatTest.res

@@ -1,7 +1,6 @@
 open JestGlobals
 open LogFormat
 
-
 // Sink detection (Reventless.AnsiStyle) defaults a non-TTY stdout — Jest
 // included — to JSON, which no-ops `bold`/`fmtComp`. The human-format
 // assertions below expect ANSI, so force text mode for this file. The
@@ -141,34 +140,47 @@ describe("LogFormat", () => {
       type command = AddProduct({productId: string, name: string, imageUrl?: string})
     }
 
-    testSync("omits an absent optional field", () => {
-      let json =
-        OptionalFieldCmd.AddProduct({productId: "prd-1", name: "Cirrus"})
-        ->Message.encode(OptionalFieldCmd.commandSchema)
-      expect(variantFields(json))->toEqual(`, {productId:"prd-1",name:"Cirrus"}`)
-    })
-
-    testSync("keeps a present optional field", () => {
-      let json =
-        OptionalFieldCmd.AddProduct({productId: "prd-1", name: "Cirrus", imageUrl: "/u/a.png"})
-        ->Message.encode(OptionalFieldCmd.commandSchema)
-      expect(variantFields(json))->toEqual(
-        `, {productId:"prd-1",name:"Cirrus",imageUrl:"/u/a.png"}`,
-      )
-    })
-
-    testSync("elides a value past the budget rather than dropping it", () => {
-      let long = String.repeat("x", maxValueChars + 20)
-      let json =
-        OptionalFieldCmd.AddProduct({productId: "prd-1", name: long})
-        ->Message.encode(OptionalFieldCmd.commandSchema)
-      let rendered = variantFields(json)
-      expect(rendered->String.includes("…(+22 chars)"))->toBe(true)
-      // The oversized value is capped, not the line: the neighbouring field that
-      // says which product this is stays intact.
-      expect(rendered->String.includes(long))->toBe(false)
-      expect(rendered->String.includes(`productId:"prd-1"`))->toBe(true)
-    })
+    testSync(
+      "omits an absent optional field",
+      () => {
+        let json =
+          OptionalFieldCmd.AddProduct({productId: "prd-1", name: "Cirrus"})->Message.encode(
+            OptionalFieldCmd.commandSchema,
+          )
+        expect(variantFields(json))->toEqual(`, {productId:"prd-1",name:"Cirrus"}`)
+      },
+    )
+
+    testSync(
+      "keeps a present optional field",
+      () => {
+        let json = OptionalFieldCmd.AddProduct({
+          productId: "prd-1",
+          name: "Cirrus",
+          imageUrl: "/u/a.png",
+        })->Message.encode(OptionalFieldCmd.commandSchema)
+        expect(
+          variantFields(json),
+        )->toEqual(`, {productId:"prd-1",name:"Cirrus",imageUrl:"/u/a.png"}`)
+      },
+    )
+
+    testSync(
+      "elides a value past the budget rather than dropping it",
+      () => {
+        let long = String.repeat("x", maxValueChars + 20)
+        let json =
+          OptionalFieldCmd.AddProduct({productId: "prd-1", name: long})->Message.encode(
+            OptionalFieldCmd.commandSchema,
+          )
+        let rendered = variantFields(json)
+        expect(rendered->String.includes("…(+22 chars)"))->toBe(true)
+        // The oversized value is capped, not the line: the neighbouring field that
+        // says which product this is stays intact.
+        expect(rendered->String.includes(long))->toBe(false)
+        expect(rendered->String.includes(`productId:"prd-1"`))->toBe(true)
+      },
+    )
   })
 })
 
@@ -207,8 +219,7 @@ let validLevels = ["DEBUG", "INFO", "WARN", "ERROR"]
 // True when a captured line is a clean JSON log record: parses as JSON, carries
 // no ANSI escape anywhere, has a string `message` and a known `level`.
 let isCleanRecord = (line: string): bool =>
-  !hasAnsi(line) &&
-  (try {
+  !hasAnsi(line) && try {
     switch line->JSON.parseOrThrow->JSON.Decode.object {
     | Some(obj) =>
       let levelOk =
@@ -222,7 +233,7 @@ let isCleanRecord = (line: string): bool =>
     }
   } catch {
   | _ => false
-  })
+  }
 
 // Read a top-level string field off a captured JSON record (None if absent).
 let fieldOf = (line: string, key: string): option<string> =>
@@ -269,8 +280,8 @@ describe("JSON sink", () => {
     // Event-collector comps carry the component *resource* name (`<Spec><Kind>`),
     // while the registry holds the bare spec name — the prefix candidate bridges them.
     Logger.registerComponentPlugin(~componentName="Products", ~pluginName="Catalog")
-    let lines = captureLogs(() =>
-      log.info(~comp="EventCollector(ProductsReadModel)", "projecting event")
+    let lines = captureLogs(
+      () => log.info(~comp="EventCollector(ProductsReadModel)", "projecting event"),
     )
     let line = lines->Array.length == 1 ? lines->Array.getUnsafe(0) : ""
     expect(lines->Array.length == 1 && line->fieldOf("plugin") == Some("Catalog"))->toBe(true)
@@ -280,8 +291,8 @@ describe("JSON sink", () => {
     // `Order` (Ordering) must not win over `OrderLines` (Billing) for `OrderLinesReadModel`.
     Logger.registerComponentPlugin(~componentName="Order", ~pluginName="Ordering")
     Logger.registerComponentPlugin(~componentName="OrderLines", ~pluginName="Billing")
-    let lines = captureLogs(() =>
-      log.info(~comp="EventCollector(OrderLinesReadModel)", "projecting event")
+    let lines = captureLogs(
+      () => log.info(~comp="EventCollector(OrderLinesReadModel)", "projecting event"),
     )
     let line = lines->Array.length == 1 ? lines->Array.getUnsafe(0) : ""
     expect(lines->Array.length == 1 && line->fieldOf("plugin") == Some("Billing"))->toBe(true)
@@ -290,14 +301,15 @@ describe("JSON sink", () => {
   testSync("dispatch annotation carries comp onto a handler line that passes none", () => {
     // What makes two collectors in one runtime process separable: the element's comp
     // comes from the dispatch boundary, not from the application's own log call.
-    let lines = captureLogs(() =>
-      EffectLogger.logInfo("projected")
-      ->Runtime.annotateInvocation(
-        ~correlationId="cid-1",
-        ~causationId="parent-1",
-        ~comp="EventCollector(ProductsReadModel)",
-      )
-      ->Effect.runSync
+    let lines = captureLogs(
+      () =>
+        EffectLogger.logInfo("projected")
+        ->Runtime.annotateInvocation(
+          ~correlationId="cid-1",
+          ~causationId="parent-1",
+          ~comp="EventCollector(ProductsReadModel)",
+        )
+        ->Effect.runSync,
     )
     let line = lines->Array.length >= 1 ? lines->Array.getUnsafe(0) : ""
     let ok =
@@ -314,52 +326,56 @@ describe("JSON sink", () => {
   })
 
   testSync("Logger.error with ~data emits one clean JSON record", () => {
-    let lines = captureLogs(() =>
-      log.error(
-        ~comp="Util_AppSync_Caller",
-        ~data=JSON.parseOrThrow(`{"errors":["boom"]}`),
-        "query errors",
-      )
+    let lines = captureLogs(
+      () =>
+        log.error(
+          ~comp="Util_AppSync_Caller",
+          ~data=JSON.parseOrThrow(`{"errors":["boom"]}`),
+          "query errors",
+        ),
     )
     expect(lines->Array.length == 1 && isCleanRecord(lines->Array.getUnsafe(0)))->toBe(true)
   })
 
   testSync("EffectLogger.logInfo emits clean JSON through install()", () => {
-    let lines = captureLogs(() =>
-      EffectLogger.logInfo(~comp="Aggregate(Product)", "replay done")->Effect.runSync
+    let lines = captureLogs(
+      () => EffectLogger.logInfo(~comp="Aggregate(Product)", "replay done")->Effect.runSync,
     )
     let allClean = lines->Array.filter(l => !isCleanRecord(l))->Array.length == 0
     expect(lines->Array.length >= 1 && allClean)->toBe(true)
   })
 
   testSync("EffectLogger.logInfo carries ~comp + ~detail as structured fields (no \\x00)", () => {
-    let lines = captureLogs(() =>
-      EffectLogger.logInfo(
-        ~comp="Aggregate(Product)",
-        ~detail=JSON.parseOrThrow(`{"id":"p-1"}`),
-        "added",
-      )->Effect.runSync
+    let lines = captureLogs(
+      () =>
+        EffectLogger.logInfo(
+          ~comp="Aggregate(Product)",
+          ~detail=JSON.parseOrThrow(`{"id":"p-1"}`),
+          "added",
+        )->Effect.runSync,
     )
-    let ok = lines->Array.some(line =>
-      switch line->JSON.parseOrThrow->JSON.Decode.object {
-      | Some(obj) =>
-        obj->Dict.get("comp")->Option.flatMap(JSON.Decode.string) == Some("Aggregate(Product)") &&
-        obj
-        ->Dict.get("detail")
-        ->Option.flatMap(JSON.Decode.object)
-        ->Option.flatMap(d => d->Dict.get("id"))
-        ->Option.flatMap(JSON.Decode.string) == Some("p-1")
-      | None => false
-      }
+    let ok = lines->Array.some(
+      line =>
+        switch line->JSON.parseOrThrow->JSON.Decode.object {
+        | Some(obj) =>
+          obj->Dict.get("comp")->Option.flatMap(JSON.Decode.string) == Some("Aggregate(Product)") &&
+            obj
+            ->Dict.get("detail")
+            ->Option.flatMap(JSON.Decode.object)
+            ->Option.flatMap(d => d->Dict.get("id"))
+            ->Option.flatMap(JSON.Decode.string) == Some("p-1")
+        | None => false
+        },
     )
     expect(ok)->toBe(true)
   })
 
   testSync("Effect.annotateLogs(correlationId) surfaces as a top-level field", () => {
-    let lines = captureLogs(() =>
-      EffectLogger.logInfo(~comp="Aggregate(Product)", "handling")
-      ->Effect.annotateLogs("correlationId", "c-123")
-      ->Effect.runSync
+    let lines = captureLogs(
+      () =>
+        EffectLogger.logInfo(~comp="Aggregate(Product)", "handling")
+        ->Effect.annotateLogs("correlationId", "c-123")
+        ->Effect.runSync,
     )
     expect(lines->Array.some(line => line->fieldOf("correlationId") == Some("c-123")))->toBe(true)
   })
@@ -368,10 +384,11 @@ describe("JSON sink", () => {
     // The component is NOT registered against any plugin; without an explicit
     // ~plugin annotation, resolvePlugin would fall back through transformations
     // and emit no plugin field. With the annotation, plugin wins.
-    let lines = captureLogs(() =>
-      EffectLogger.logInfo(~comp="Aggregate(Unregistered)", "handling")
-      ->Effect.annotateLogs("plugin", "Ordering")
-      ->Effect.runSync
+    let lines = captureLogs(
+      () =>
+        EffectLogger.logInfo(~comp="Aggregate(Unregistered)", "handling")
+        ->Effect.annotateLogs("plugin", "Ordering")
+        ->Effect.runSync,
     )
     expect(lines->Array.some(line => line->fieldOf("plugin") == Some("Ordering")))->toBe(true)
   })
@@ -398,14 +415,17 @@ describe("JSON sink", () => {
     let detail = Dict.fromArray([("blob", JSON.Encode.string(big))])->JSON.Encode.object
     // ~detail flows through emit (Logger.t's ~data goes into the message instead).
     let direct = captureLogs(() => Logger.emit(~level=Info, ~comp="Platform", ~detail, "big"))
-    let ok = switch direct->Array.get(0)->Option.flatMap(l => l->JSON.parseOrThrow->JSON.Decode.object) {
+    let ok = switch direct
+    ->Array.get(0)
+    ->Option.flatMap(l => l->JSON.parseOrThrow->JSON.Decode.object) {
     | Some(obj) =>
       switch obj->Dict.get("detail")->Option.flatMap(JSON.Decode.object) {
       | Some(d) =>
         d->Dict.get("truncated")->Option.flatMap(JSON.Decode.bool) == Some(true) &&
-          d->Dict.get("preview")->Option.flatMap(JSON.Decode.string)->Option.mapOr(false, p =>
-            p->String.length <= 512
-          )
+          d
+          ->Dict.get("preview")
+          ->Option.flatMap(JSON.Decode.string)
+          ->Option.mapOr(false, p => p->String.length <= 512)
       | None => false
       }
     | None => false
@@ -425,7 +445,9 @@ describe("JSON sink", () => {
     let cmd: Message.commandJson = {
       Message.id: "0",
       meta,
-      commandJson: (Heartbeat("0.0.0"): PluginSpec.command)->Message.encode(PluginSpec.commandSchema),
+      commandJson: (Heartbeat("0.0.0"): PluginSpec.command)->Message.encode(
+        PluginSpec.commandSchema,
+      ),
     }
     let name = cmd->cmdName
     expect(!hasAnsi(name) && name == "Heartbeat")->toBe(true)

package/tests/logger/LoggerLazyTest.res

@@ -8,29 +8,38 @@ describe("Logger.debugLazy", () => {
   testSync("does NOT invoke the thunk at the default Info level", () => {
     let called = ref(false)
     let log = Logger.makeLogger(~minLevel=Logger.Info)
-    log.debugLazy(~comp="Test", () => {
-      called := true
-      "should never be built"
-    })
+    log.debugLazy(
+      ~comp="Test",
+      () => {
+        called := true
+        "should never be built"
+      },
+    )
     expect(called.contents)->toEqual(false)
   })
 
   testSync("invokes the thunk when debug output is enabled", () => {
     let called = ref(false)
     let log = Logger.makeLogger(~minLevel=Logger.Debug)
-    log.debugLazy(~comp="Test", () => {
-      called := true
-      "built"
-    })
+    log.debugLazy(
+      ~comp="Test",
+      () => {
+        called := true
+        "built"
+      },
+    )
     expect(called.contents)->toEqual(true)
   })
 
   testSync("the silent logger never invokes the thunk", () => {
     let called = ref(false)
-    Logger.silent.debugLazy(~comp="Test", () => {
-      called := true
-      "x"
-    })
+    Logger.silent.debugLazy(
+      ~comp="Test",
+      () => {
+        called := true
+        "x"
+      },
+    )
     expect(called.contents)->toEqual(false)
   })
 })

package/tests/message/MessageTest.res

@@ -97,67 +97,70 @@ describe("Message should", () => {
   // before later pluginStructure fields like `events`/`chapter`) existed must still
   // decode — otherwise the one stale event bricks the whole lifecycle aggregate. See
   // docs/plans/done/platform-infrastructure-in-plugin-list.md (durable fix option 2).
-  testSync("tolerantly decode a VersionConnected persisted before kind/structure fields existed", () => {
-    open PluginSpec
-    let def: Reventless.Plugin.pluginDefinition = {
-      id: "id",
-      name: "Ordering",
-      version: "1.0.0",
-      extensionPoints: [],
-      extensions: [],
-      eventCollector: "arn",
-      extensionProtocols: [],
-      apiSchemaFragment: None,
-      apiTarget: None,
-      structure: Some(Reventless.Offload.Inline({
-        readModels: [],
-        stateViewSlices: [],
-        stateChangeSlices: [],
-        aggregates: [
-          {
-            name: "Order",
-            commands: [],
-            producedEventTypes: [],
-            consumedEventTypes: [],
-            linkedViews: [],
-            consistencyRead: None,
-            events: [],
-            errors: [],
-            chapter: None,
-          },
-        ],
-        automationSlices: [],
-        outboundTranslationSlices: [],
-        inboundTranslationSlices: [],
+  testSync(
+    "tolerantly decode a VersionConnected persisted before kind/structure fields existed",
+    () => {
+      open PluginSpec
+      let def: Reventless.Plugin.pluginDefinition = {
+        id: "id",
+        name: "Ordering",
+        version: "1.0.0",
+        extensionPoints: [],
         extensions: [],
-        extensionPoints: None,
-        requiredStores: None,
-        requiredStoreDeclarations: None,
-        requiredCapabilities: None,
-        traitDeclarations: None,
-      })),
-      dcbEventLog: None,
-      kind: Domain,
-    }
-    let event' = {
-      id: "id",
-      meta: {
-        service: "svc",
-        time: "t",
-        ip: "ip",
-        user: "u",
-        msgId: "m",
-        correlationId: "c",
-      },
-      event: VersionConnected(def),
-    }
-    let json = event'->Message.encodeEvent'(S.string, PluginSpec.eventSchema)
-
-    // Simulate the persisted JSON as written before these fields existed: drop the
-    // mandatory enum `kind`, a top-level `T | null` field, and two nested writableDef
-    // fields (a mandatory array + a `T | null`).
-    let oldJson =
-      %raw(`function(j){
+        eventCollector: "arn",
+        extensionProtocols: [],
+        apiSchemaFragment: None,
+        apiTarget: None,
+        structure: Some(
+          Reventless.Offload.Inline({
+            readModels: [],
+            stateViewSlices: [],
+            stateChangeSlices: [],
+            aggregates: [
+              {
+                name: "Order",
+                commands: [],
+                producedEventTypes: [],
+                consumedEventTypes: [],
+                linkedViews: [],
+                consistencyRead: None,
+                events: [],
+                errors: [],
+                chapter: None,
+              },
+            ],
+            automationSlices: [],
+            outboundTranslationSlices: [],
+            inboundTranslationSlices: [],
+            extensions: [],
+            extensionPoints: None,
+            requiredStores: None,
+            requiredStoreDeclarations: None,
+            requiredCapabilities: None,
+            traitDeclarations: None,
+          }),
+        ),
+        dcbEventLog: None,
+        kind: Domain,
+      }
+      let event' = {
+        id: "id",
+        meta: {
+          service: "svc",
+          time: "t",
+          ip: "ip",
+          user: "u",
+          msgId: "m",
+          correlationId: "c",
+        },
+        event: VersionConnected(def),
+      }
+      let json = event'->Message.encodeEvent'(S.string, PluginSpec.eventSchema)
+
+      // Simulate the persisted JSON as written before these fields existed: drop the
+      // mandatory enum `kind`, a top-level `T | null` field, and two nested writableDef
+      // fields (a mandatory array + a `T | null`).
+      let oldJson = %raw(`function(j){
         var c = JSON.parse(JSON.stringify(j));
         var d = c.event._0;
         delete d.kind;
@@ -168,35 +171,36 @@ describe("Message should", () => {
         return c;
       }`)(json)
 
-    // Strict decode must reject the stale JSON — the tolerance is what saves it.
-    let strictThrew = switch oldJson->Reventless.Util_Sury.fromJson(
-      Message.toEventSchema'(S.string, PluginSpec.eventSchema),
-    ) {
-    | _ => false
-    | exception _ => true
-    }
-    expect(strictThrew)->toBe(true)
-
-    // Tolerant decode heals: kind -> Domain (first variant), missing array -> [],
-    // missing `T | null` fields -> None.
-    let decoded = oldJson->Message.decodeEvent'(S.string, PluginSpec.eventSchema)
-    switch decoded.event {
-    | VersionConnected(d) =>
-      expect(
-        switch d.kind {
-        | Domain => "Domain"
-        | _ => "other"
-        },
-      )->toBe("Domain")
-      expect(d.apiSchemaFragment->Option.isNone)->toBe(true)
-      let structure: Reventless.Plugin.pluginStructure =
-        d.structure->Option.flatMap(Reventless.Offload.getInline)->Option.getOrThrow
-      let agg = structure.aggregates->Array.getUnsafe(0)
-      expect(agg.events->Array.length)->toBe(0)
-      expect(agg.chapter->Option.isNone)->toBe(true)
-    | _ => expect("wrong-variant")->toBe("VersionConnected")
-    }
-  })
+      // Strict decode must reject the stale JSON — the tolerance is what saves it.
+      let strictThrew = switch oldJson->Reventless.Util_Sury.fromJson(
+        Message.toEventSchema'(S.string, PluginSpec.eventSchema),
+      ) {
+      | _ => false
+      | exception _ => true
+      }
+      expect(strictThrew)->toBe(true)
+
+      // Tolerant decode heals: kind -> Domain (first variant), missing array -> [],
+      // missing `T | null` fields -> None.
+      let decoded = oldJson->Message.decodeEvent'(S.string, PluginSpec.eventSchema)
+      switch decoded.event {
+      | VersionConnected(d) =>
+        expect(
+          switch d.kind {
+          | Domain => "Domain"
+          | _ => "other"
+          },
+        )->toBe("Domain")
+        expect(d.apiSchemaFragment->Option.isNone)->toBe(true)
+        let structure: Reventless.Plugin.pluginStructure =
+          d.structure->Option.flatMap(Reventless.Offload.getInline)->Option.getOrThrow
+        let agg = structure.aggregates->Array.getUnsafe(0)
+        expect(agg.events->Array.length)->toBe(0)
+        expect(agg.chapter->Option.isNone)->toBe(true)
+      | _ => expect("wrong-variant")->toBe("VersionConnected")
+      }
+    },
+  )
 
   // The exact aggregate-replay path: EventLog_Operations.decodeEvent reassembles the
   // event variant and calls `Message.decode(Spec.eventSchema)`. This is what actually
@@ -218,10 +222,9 @@ describe("Message should", () => {
       kind: Domain,
     }
     let variantJson = VersionConnected(def)->Message.encode(PluginSpec.eventSchema)
-    let staleJson =
-      %raw(`function(j){ var c = JSON.parse(JSON.stringify(j)); delete c._0.kind; return c; }`)(
-        variantJson,
-      )
+    let staleJson = %raw(`function(j){ var c = JSON.parse(JSON.stringify(j)); delete c._0.kind; return c; }`)(
+      variantJson,
+    )
 
     // Strict decode of the stale variant throws (reproduces the production brick).
     let strictThrew = switch staleJson->Reventless.Util_Sury.fromJson(PluginSpec.eventSchema) {

package/tests/message/MetaEnvelopeTest.res

@@ -129,10 +129,7 @@ describe("StoredEvent encode/decode round-trip:", () => {
       position: "000000001",
       event: "ItemCreated",
       data: JSON.Object(
-        Dict.fromArray([
-          ("itemId", JSON.String("agg-1")),
-          ("name", JSON.String("Widget")),
-        ]),
+        Dict.fromArray([("itemId", JSON.String("agg-1")), ("name", JSON.String("Widget"))]),
       ),
       meta,
       recordedAt: "2026-05-13T10:00:00.000Z",
@@ -157,10 +154,7 @@ describe("StoredEvent encode/decode round-trip:", () => {
       data: JSON.Object(Dict.fromArray([("productId", JSON.String("p-1"))])),
       meta,
       recordedAt: "2026-05-13T10:00:00.000Z",
-      tags: [
-        {key: "productId", value: "p-1"},
-        {key: "categoryId", value: "c-1"},
-      ],
+      tags: [{key: "productId", value: "p-1"}, {key: "categoryId", value: "c-1"}],
     }
     let flat = stored->storedEventToFlatJson(S.string)
     let roundTrip = flat->flatJsonToStoredEvent(S.string)
@@ -175,26 +169,28 @@ describe("StoredEvent encode/decode round-trip:", () => {
     expect(first.value)->toBe("p-1")
   })
 
-  testSync("meta is flattened to top-level keys in the on-disk JSON (DynamoDB GSI projectability)", () => {
-    let meta = generateMeta(~service="catalog")
-    let stored: Reventless.StoredEvent.storedEvent<string> = {
-      id: "agg-1",
-      position: "000000001",
-      event: "ItemCreated",
-      data: JSON.Object(Dict.make()),
-      meta,
-      recordedAt: "2026-05-13T10:00:00.000Z",
-    }
-    let flat = stored->storedEventToFlatJson(S.string)
-    let obj = flat->JSON.Decode.object->Option.getOrThrow
-    // meta.* should be top-level (not nested under "meta")
-    expect(obj->Dict.get("meta"))->toEqual(None)->ignore
-    expect(obj->Dict.get("service"))->toEqual(Some(JSON.String("catalog")))->ignore
-    expect(obj->Dict.get("msgId")->Option.isSome)->toBe(true)->ignore
-    // envelope fields are also top-level
-    expect(obj->Dict.get("position"))->toEqual(Some(JSON.String("000000001")))->ignore
-    expect(obj->Dict.get("event"))->toEqual(Some(JSON.String("ItemCreated")))->ignore
-    expect(obj->Dict.get("recordedAt"))
-    ->toEqual(Some(JSON.String("2026-05-13T10:00:00.000Z")))
-  })
+  testSync(
+    "meta is flattened to top-level keys in the on-disk JSON (DynamoDB GSI projectability)",
+    () => {
+      let meta = generateMeta(~service="catalog")
+      let stored: Reventless.StoredEvent.storedEvent<string> = {
+        id: "agg-1",
+        position: "000000001",
+        event: "ItemCreated",
+        data: JSON.Object(Dict.make()),
+        meta,
+        recordedAt: "2026-05-13T10:00:00.000Z",
+      }
+      let flat = stored->storedEventToFlatJson(S.string)
+      let obj = flat->JSON.Decode.object->Option.getOrThrow
+      // meta.* should be top-level (not nested under "meta")
+      expect(obj->Dict.get("meta"))->toEqual(None)->ignore
+      expect(obj->Dict.get("service"))->toEqual(Some(JSON.String("catalog")))->ignore
+      expect(obj->Dict.get("msgId")->Option.isSome)->toBe(true)->ignore
+      // envelope fields are also top-level
+      expect(obj->Dict.get("position"))->toEqual(Some(JSON.String("000000001")))->ignore
+      expect(obj->Dict.get("event"))->toEqual(Some(JSON.String("ItemCreated")))->ignore
+      expect(obj->Dict.get("recordedAt"))->toEqual(Some(JSON.String("2026-05-13T10:00:00.000Z")))
+    },
+  )
 })