@starci/hfs 4.7.31 → 4.7.33

package/templates/be/inbox/platform/inbox/request-fingerprint.policy.spec.ts.tpl

@@ -0,0 +1,76 @@
+import { Test } from "@nestjs/testing"
+import { IdempotencyError, IdempotencyErrorCode } from "@modules/platform/idempotency"
+import { requestFingerprint } from "./request-fingerprint.policy"
+
+const FINGERPRINT = Symbol("fingerprint")
+const build = async () => {
+    const moduleRef = await Test.createTestingModule({
+        providers: [{ provide: FINGERPRINT, useValue: requestFingerprint }],
+    }).compile()
+    return moduleRef.get<typeof requestFingerprint>(FINGERPRINT)
+}
+
+describe("requestFingerprint", () => {
+    it("hashes nested objects independently of property insertion order", async () => {
+        const fingerprint = await build()
+
+        expect(fingerprint({ personId: "person-1", body: { quantity: 2, productId: "product-1" } })).toBe(
+            fingerprint({ body: { productId: "product-1", quantity: 2 }, personId: "person-1" }),
+        )
+        expect(fingerprint({ a: 1 })).toMatch(/^[a-f0-9]{64}$/)
+    })
+
+    it("keeps binary UTF-16 key order for non-ASCII and supplementary Unicode keys", async () => {
+        const fingerprint = await build()
+        const body = { "\uE000": 5, "\u{1F600}": 4, "\u00E9": 1, a: 3, Z: 2 }
+
+        expect(fingerprint(body)).toBe(fingerprint({ Z: 2, a: 3, "\u00E9": 1, "\u{1F600}": 4, "\uE000": 5 }))
+        expect(fingerprint(body)).toBe("6eb3469044da5c7df68404ba05b90306384fc773ad605d4de06321a2092ff365")
+    })
+
+    it("preserves array order, JSON types and nested values", async () => {
+        const fingerprint = await build()
+
+        expect(fingerprint([1, 2])).not.toBe(fingerprint([2, 1]))
+        expect(fingerprint({ value: 1 })).not.toBe(fingerprint({ value: "1" }))
+        expect(fingerprint({ body: { quantity: 2 } })).not.toBe(fingerprint({ body: { quantity: 3 } }))
+        expect(new Set([null, true, false, "", 0].map(fingerprint)).size).toBe(5)
+        expect(fingerprint([])).not.toBe(fingerprint({}))
+    })
+
+    it("accepts an object without a prototype and repeated noncyclic references", async () => {
+        const fingerprint = await build()
+        const shared = { quantity: 2 }
+        const withoutPrototype: unknown = Object.assign(Object.create(null), { quantity: 2 })
+
+        expect(fingerprint(withoutPrototype)).toBe(fingerprint(shared))
+        expect(fingerprint([shared, shared])).toBe(fingerprint([{ quantity: 2 }, { quantity: 2 }]))
+    })
+
+    it.each([
+        [undefined],
+        [() => 1],
+        [Symbol("unsupported")],
+        [BigInt(1)],
+        [Number.NaN],
+        [Number.POSITIVE_INFINITY],
+        [Number.NEGATIVE_INFINITY],
+        [{ missing: undefined }],
+        [[undefined]],
+        [Array(1)],
+        [new Date("2026-10-24T00:00:00.000Z")],
+        [new Map([["quantity", 2]])],
+    ])("refuses values that cannot represent a JSON request: %p", async (request: unknown) => {
+        const fingerprint = await build()
+
+        expect(() => fingerprint(request)).toThrow(new IdempotencyError({ code: IdempotencyErrorCode.RequestInvalid }))
+    })
+
+    it("refuses cyclic requests before a claim can be written", async () => {
+        const fingerprint = await build()
+        const cyclic: Record<string, unknown> = { quantity: 2 }
+        cyclic.body = cyclic
+
+        expect(() => fingerprint(cyclic)).toThrow(new IdempotencyError({ code: IdempotencyErrorCode.RequestInvalid }))
+    })
+})

package/templates/be/inbox/platform/inbox/request-fingerprint.policy.ts.tpl

@@ -0,0 +1,36 @@
+import { createHash } from "node:crypto"
+import { IdempotencyError, IdempotencyErrorCode } from "@modules/platform/idempotency"
+
+/** Serializes JSON without depending on object insertion order; array order remains part of the request. */
+const serializeJson = (value: unknown, ancestors: Set<object>): string => {
+    if (value === null || typeof value === "string" || typeof value === "boolean") return JSON.stringify(value)
+    if (typeof value === "number" && Number.isFinite(value)) return JSON.stringify(value)
+    if (typeof value !== "object" || ancestors.has(value))
+        throw new IdempotencyError({ code: IdempotencyErrorCode.RequestInvalid })
+    ancestors.add(value)
+    let serialized: string
+    if (Array.isArray(value)) {
+        serialized = `[${Array.from(value, (item: unknown) => serializeJson(item, ancestors)).join(",")}]`
+    } else {
+        const prototype: unknown = Object.getPrototypeOf(value)
+        if (prototype !== Object.prototype && prototype !== null) {
+            throw new IdempotencyError({ code: IdempotencyErrorCode.RequestInvalid })
+        }
+        serialized = `{${Object.keys(value)
+            .sort((left, right) => Number(left > right) - Number(left < right))
+            .map((key) => {
+                const item: unknown = Reflect.get(value, key)
+                return `${JSON.stringify(key)}:${serializeJson(item, ancestors)}`
+            })
+            .join(",")}}`
+    }
+    ancestors.delete(value)
+    return serialized
+}
+
+/** Returns a stable JSON representation for both the request digest and the stored outcome. */
+export const canonicalJson = (value: unknown): string => serializeJson(value, new Set())
+
+/** Hashes the validated client request, so a reused key cannot silently apply a different body. */
+export const requestFingerprint = (request: unknown): string =>
+    createHash("sha256").update(canonicalJson(request)).digest("hex")

package/templates/be/inbox/platform/migration.sql.tpl

@@ -21,6 +21,7 @@ revoke all on table public.inbox from public, anon, authenticated;
 grant select, insert on table public.inbox to app_be;
 
 create table public.event_bus (
+    correlation_id varchar(128) not null,
     event_id text primary key check (event_id <> ''),
     event_name text not null check (event_name <> ''),
     payload jsonb not null,

package/templates/be/inbox/service.spec.ts.tpl

@@ -31,7 +31,7 @@ describe("@@Provider@@InboxService", () => {
         it("claims, records and publishes a typed event in the same transaction", async () => {
             const { inbox, claims, events, entityManager, transaction } = await build(true)
 
-            await inbox.record@@Provider@@Delivery({ eventId: "delivery-1", delivery: DELIVERY })
+            await inbox.record@@Provider@@Delivery({ eventId: "delivery-1", delivery: DELIVERY, correlationId: "request-1" })
 
             expect(entityManager.query).toHaveBeenCalledTimes(1)
             expect(entityManager.query).toHaveBeenCalledWith(INSERT_@@providerUpper@@_INBOX, ["@@provider@@", "delivery-1", JSON.stringify(DELIVERY)])
@@ -45,7 +45,7 @@ describe("@@Provider@@InboxService", () => {
         it("acknowledges a duplicate @@provider@@ delivery without further work", async () => {
             const { inbox, events, entityManager, transaction } = await build(false)
 
-            await inbox.record@@Provider@@Delivery({ eventId: "delivery-1", delivery: DELIVERY })
+            await inbox.record@@Provider@@Delivery({ eventId: "delivery-1", delivery: DELIVERY, correlationId: "request-1" })
 
             expect(entityManager.query).not.toHaveBeenCalled()
             expect(events.events).toEqual([])
@@ -55,7 +55,7 @@ describe("@@Provider@@InboxService", () => {
         it("does not publish for an already recorded receipt", async () => {
             const { inbox, events, transaction } = await build(true, [])
 
-            await inbox.record@@Provider@@Delivery({ eventId: "delivery-1", delivery: DELIVERY })
+            await inbox.record@@Provider@@Delivery({ eventId: "delivery-1", delivery: DELIVERY, correlationId: "request-1" })
 
             expect(events.events).toEqual([])
             expect(transaction.commits).toBe(1)
@@ -66,7 +66,7 @@ describe("@@Provider@@InboxService", () => {
             const failure = new Error("outbox unavailable")
             events.failNext("publish", failure)
 
-            await expect(inbox.record@@Provider@@Delivery({ eventId: "delivery-1", delivery: DELIVERY })).rejects.toBe(failure)
+            await expect(inbox.record@@Provider@@Delivery({ eventId: "delivery-1", delivery: DELIVERY, correlationId: "request-1" })).rejects.toBe(failure)
 
             expect(transaction.rollbacks).toBe(1)
             expect(transaction.commits).toBe(0)

package/templates/be/inbox/service.ts.tpl

@@ -13,6 +13,8 @@ interface @@Provider@@Delivery {
 }
 
 interface @@Provider@@DeliveryRequest {
+    /** The request identity carried into the event envelope. */
+    readonly correlationId: string
     readonly eventId: string | undefined
     readonly delivery: @@Provider@@Delivery
 }
@@ -38,7 +40,7 @@ export class @@Provider@@InboxService {
                 payload: request.delivery,
             })
             if (receiptId === undefined) return
-            await this.eventBus.publish(@@Provider@@DeliveryRecordedEvent.create({ receiptId }), manager)
+            await this.eventBus.publish(@@Provider@@DeliveryRecordedEvent.create({ receiptId }), manager, request.correlationId)
         })
     }
 }

package/templates/be/inbox/webhook-door.spec.ts.tpl

@@ -7,6 +7,7 @@ import { @@Provider@@InboxService } from "@modules/domain/@@provider@@-inbox"
 import { Secret } from "@modules/platform/config"
 import { HttpSecurityModule, WebhookSignatureService } from "@modules/platform/http-security"
 import type { HttpSecurityOptions } from "@modules/platform/http-security"
+import type { CorrelationRequest } from "@modules/platform/logging"
 import { @@Event@@Request } from "./dto/@@event@@.request"
 import { @@Provider@@Webhook } from "./@@provider@@.webhook"
 
@@ -24,7 +25,7 @@ const deliveryOf = (): @@Event@@Request => {
 
 const DELIVERY = deliveryOf()
 const RAW_BODY = Buffer.from(JSON.stringify(DELIVERY))
-const REQUEST = mock<RawBodyRequest<Request>>({ rawBody: RAW_BODY })
+const REQUEST = mock<RawBodyRequest<Request> & CorrelationRequest>({ rawBody: RAW_BODY, correlationId: "request-1" })
 
 const OPTIONS: HttpSecurityOptions = {
     allowedOrigins: [],
@@ -58,7 +59,7 @@ describe("@@Provider@@Webhook", () => {
             await door.receive(REQUEST, sign(RAW_BODY, SIGNED_AT), SIGNED_AT, DELIVERY_ID, DELIVERY)
 
             expect(deliveries.record@@Provider@@Delivery).toHaveBeenCalledTimes(1)
-            expect(deliveries.record@@Provider@@Delivery).toHaveBeenCalledWith({ eventId: DELIVERY_ID, delivery: DELIVERY })
+            expect(deliveries.record@@Provider@@Delivery).toHaveBeenCalledWith({ eventId: DELIVERY_ID, delivery: DELIVERY, correlationId: "request-1" })
         })
 
         it("never reaches the inbox when the signature is not the provider's", async () => {

package/templates/be/inbox/webhook-door.ts.tpl

@@ -5,6 +5,7 @@ import { Public, PublicReason } from "@modules/domain/identity"
 import { @@Provider@@InboxService } from "@modules/domain/@@provider@@-inbox"
 import { InjectWebhookSignature, RateLimit, RateTier } from "@modules/platform/http-security"
 import type { WebhookSignatureService } from "@modules/platform/http-security"
+import type { CorrelationRequest } from "@modules/platform/logging"
 import { @@Event@@Request } from "./dto/@@event@@.request"
 
 @Controller("webhooks/@@provider@@")
@@ -25,13 +26,13 @@ export class @@Provider@@Webhook {
     @Public({ reason: PublicReason.SignedWebhook })
     @RateLimit(RateTier.Strict)
     async receive(
-        @Req() request: RawBodyRequest<Request>,
+        @Req() request: RawBodyRequest<Request> & CorrelationRequest,
         @Headers("x-@@provider@@-signature") signature: string | undefined,
         @Headers("x-@@provider@@-timestamp") timestamp: string | undefined,
         @Headers("x-@@provider@@-delivery-id") deliveryId: string | undefined,
         @Body() delivery: @@Event@@Request,
     ): Promise<void> {
         this.signature.verify({ provider: "@@provider@@", rawBody: request.rawBody, signature, timestamp })
-        await this.deliveries.record@@Provider@@Delivery({ eventId: deliveryId, delivery })
+        await this.deliveries.record@@Provider@@Delivery({ eventId: deliveryId, delivery, correlationId: request.correlationId })
     }
 }

package/templates/be/patterns/event-bus/platform/errors/event-bus.error.ts.tpl

@@ -3,6 +3,8 @@ import type { ErrorKind } from "@modules/platform/errors"
 
 /** Codes of the event-bus capability. */
 export enum EventBusErrorCode {
+    /** A publisher supplied an unsafe or unbounded request identity. */
+    CorrelationInvalid = "EVENT_BUS_CORRELATION_INVALID",
     /** The broker did not answer a call within its deadline, or refused it. */
     BrokerUnavailable = "EVENT_BUS_BROKER_UNAVAILABLE",
     /** A dead letter id does not name a message the dead-letter topic holds. */
@@ -11,6 +13,7 @@ export enum EventBusErrorCode {
 
 /** How each event-bus code travels. */
 export const EVENT_BUS_ERROR_KINDS: Record<EventBusErrorCode, ErrorKind> = {
+    [EventBusErrorCode.CorrelationInvalid]: "invalid",
     [EventBusErrorCode.BrokerUnavailable]: "unavailable",
     [EventBusErrorCode.DeadLetterUnknown]: "not-found",
 }

package/templates/be/patterns/event-bus/platform/event-bus.contracts.ts.tpl

@@ -25,6 +25,8 @@ export interface EventClass<Event extends BaseEvent> {
 
 /** An event as a consumer receives it. */
 export interface EventDelivery<Event extends BaseEvent> {
+    /** The originating request id, carried explicitly across the broker. */
+    readonly correlationId: string
     /** The stable event id: the dedupe key of the receiver. */
     readonly eventId: string
     /** The event. */
@@ -47,8 +49,16 @@ export interface EventDeadLetter {
     readonly attempts: number
 }
 
+/** Explicit request context carried independently of the business payload. */
+export interface EventMetadata {
+    /** The originating request or promoted legacy event identity. */
+    readonly correlationId: string
+}
+
 /** The envelope of an event on the wire: what the outbox row stores and a consumer reads back. */
 export interface EventEnvelope {
+    /** Request context that belongs to transport metadata rather than the business payload. */
+    readonly metadata: EventMetadata
     /** The stable event id. */
     readonly eventId: string
     /** The event name. */

package/templates/be/patterns/event-bus/platform/event-bus.port.ts.tpl

@@ -3,8 +3,8 @@ import type { BaseEvent, EventClass, EventDeadLetter, EventDelivery } from "./ev
 
 /** The event bus of a service: events leave it through `publish`, called by a domain service in the transaction of the change they report. */
 export interface EventBus {
-    /** Writes the event in the outbox of the transaction `tx` carries; the relay hands it to the broker once the transaction commits. */
-    publish(event: BaseEvent, tx: EntityManager): Promise<void>
+    /** Writes the event and explicit request id in the outbox of `tx`; the relay sends them after commit. */
+    publish(event: BaseEvent, tx: EntityManager, correlationId: string): Promise<void>
     /** How many deliveries of the class wait on the retry topic for their backoff to pass. */
     pendingRetries(event: EventClass<BaseEvent>): Promise<number>
     /** The events of the class that ran out of attempts. */

package/templates/be/patterns/event-bus/platform/event-bus.service.spec.ts.tpl

@@ -46,7 +46,7 @@ class PingEvent extends BaseEvent {
 
 const DLQ = "run-1.events.probe.dlq"
 
-const envelope = (eventName: string, eventId: string) => JSON.stringify({ eventId, eventName, payload: {} })
+const envelope = (eventName: string, eventId: string) => JSON.stringify({ metadata: { correlationId: `request-${eventId}` }, eventId, eventName, payload: {} })
 
 const letter = (offset: string, eventName: string, headers: Record<string, string>): InboundMessage => ({
     topic: DLQ,
@@ -72,19 +72,32 @@ const build = async () => {
 
 describe("EventBusService", () => {
     describe("publish", () => {
+        it.each(["", "unsafe\nid", "x".repeat(129)])("refuses an invalid correlation id before SQL: %s", async (correlationId) => {
+            const tx = mockEntityManager({ query: [INSERT_OUTBOX_ROW, []] })
+            const { bus, transport } = await build()
+
+            await expect(bus.publish(new PingEvent("e-1", { note: "hi" }), tx, correlationId)).rejects.toMatchObject({
+                code: EventBusErrorCode.CorrelationInvalid,
+            })
+
+            expect(tx.query).not.toHaveBeenCalled()
+            expect(transport.send).not.toHaveBeenCalled()
+        })
+
         it("writes the envelope as an outbox row of the caller transaction, keyed by the event id on the topic of the service", async () => {
             const tx = mockEntityManager({ query: [INSERT_OUTBOX_ROW, []] })
             const { bus, transport } = await build()
 
-            await bus.publish(new PingEvent("e-1", { note: "hi" }), tx)
+            await bus.publish(new PingEvent("e-1", { note: "hi" }), tx, "request-1")
 
             expect(tx.query).toHaveBeenCalledWith(INSERT_OUTBOX_ROW, [
                 "e-1",
                 "probe.ping",
                 "run-1.events.probe",
                 "e-1",
-                JSON.stringify({ eventId: "e-1", eventName: "probe.ping", payload: { note: "hi" } }),
+                JSON.stringify({ metadata: { correlationId: "request-1" }, eventId: "e-1", eventName: "probe.ping", payload: { note: "hi" } }),
                 new Date(AT),
+                "request-1",
             ])
             expect(transport.send).not.toHaveBeenCalled()
         })

package/templates/be/patterns/event-bus/platform/event-bus.service.ts.tpl

@@ -2,6 +2,7 @@ import { Injectable } from "@nestjs/common"
 import type { EntityManager } from "typeorm"
 import { InjectClock } from "@modules/platform/clock"
 import type { Clock } from "@modules/platform/clock"
+import { isCorrelationId } from "@modules/platform/logging"
 import { EventBusError, EventBusErrorCode } from "./errors/event-bus.error"
 import type { BaseEvent, EventClass, EventDeadLetter, EventEnvelope } from "./event-bus.contracts"
 import { InjectEventBusOptions, InjectEventTransport } from "./event-bus.decorators"
@@ -42,9 +43,15 @@ export class EventBusService implements EventBus {
         @InjectClock() private readonly clock: Clock,
     ) {}
 
-    /** Writes the event in the outbox of the transaction `tx`; the event id is the partition key, so the events of one aggregate keep their order. */
-    async publish(event: BaseEvent, tx: EntityManager): Promise<void> {
-        const envelope: EventEnvelope = { eventId: event.eventId, eventName: event.eventName, payload: event.payload }
+    /** Writes the event and explicit request id in the outbox of `tx`; the event id is the partition key. */
+    async publish(event: BaseEvent, tx: EntityManager, correlationId: string): Promise<void> {
+        if (!isCorrelationId(correlationId)) throw new EventBusError({ code: EventBusErrorCode.CorrelationInvalid })
+        const envelope: EventEnvelope = {
+            metadata: { correlationId },
+            eventId: event.eventId,
+            eventName: event.eventName,
+            payload: event.payload,
+        }
         await tx.query(INSERT_OUTBOX_ROW, [
             event.eventId,
             event.eventName,
@@ -52,6 +59,7 @@ export class EventBusService implements EventBus {
             event.eventId,
             JSON.stringify(envelope),
             this.clock.now(),
+            correlationId,
         ])
     }
 

package/templates/be/patterns/event-bus/platform/event-envelope.policy.spec.ts.tpl

@@ -1,3 +1,4 @@
+import { Test } from "@nestjs/testing"
 import { BaseEvent } from "./event-bus.contracts"
 import { readEnvelope, readEnvelopeText, readEventOf } from "./event-envelope.policy"
 
@@ -20,71 +21,159 @@ const isPingPayload = (payload: Record<string, unknown>): payload is PingPayload
     typeof payload.note === "string"
 const buildPing = (eventId: string, payload: PingPayload): PingEvent => new PingEvent(eventId, payload)
 
-describe("event envelope policies", () => {
-    describe("readEnvelope", () => {
-        it("reads the event id and payload of an envelope", () => {
-            expect(readEnvelope({ eventId: "event-1", payload: { note: "hello" }, ignored: true })).toEqual({
-                eventId: "event-1",
-                payload: { note: "hello" },
-            })
-        })
+const POLICY = Symbol("policy")
+const policyFunctions = { readEnvelope, readEnvelopeText, readEventOf }
+const build = async () => {
+    const moduleRef = await Test.createTestingModule({
+        providers: [{ provide: POLICY, useFactory: () => policyFunctions }],
+    }).compile()
+    return moduleRef.get<typeof policyFunctions>(POLICY)
+}
+
+describe("event envelope policies readEnvelope", () => {
+    it("reads the event id and payload of an envelope", async () => {
+        const policy = await build()
 
-        it.each([
-            [null, "a non-record"],
-            [{ eventId: 1, payload: {} }, "a non-text event id"],
-            [{ eventId: "event-1", payload: 1 }, "a non-record payload"],
-        ])("refuses %s because it is %s", (envelope: unknown, _why: string) => {
-            expect(readEnvelope(envelope)).toBeNull()
+        expect(policy.readEnvelope({ eventId: "event-1", payload: { note: "hello" }, ignored: true })).toEqual({
+            eventId: "event-1",
+            payload: { note: "hello" },
         })
     })
 
-    describe("readEnvelopeText", () => {
-        it("parses an envelope and names its event", () => {
-            const envelope = { eventId: "event-1", eventName: "probe.ping", payload: { note: "hello" } }
+    it.each([
+        [null, "a non-record"],
+        [{ eventId: 1, payload: {} }, "a non-text event id"],
+        [{ eventId: "event-1", payload: 1 }, "a non-record payload"],
+    ])("refuses %s because it is %s", async (envelope: unknown, _why: string) => {
+        const policy = await build()
 
-            expect(readEnvelopeText(JSON.stringify(envelope))).toEqual({
-                eventName: "probe.ping",
-                envelope,
-                cause: null,
-            })
-        })
+        expect(policy.readEnvelope(envelope)).toBeNull()
+    })
+})
 
-        it.each([JSON.stringify([]), JSON.stringify({ eventName: 1 })])(
-            "keeps a parsed JSON value without a text event name unnamed",
-            (value) => {
-                expect(readEnvelopeText(value)).toMatchObject({ eventName: "", cause: null })
-            },
-        )
+describe("event envelope policies current correlation metadata", () => {
+    it("parses an envelope and names its event", async () => {
+        const policy = await build()
 
-        it("returns the parse failure for text that is not JSON", () => {
-            const result = readEnvelopeText("not json")
+        const envelope = {
+            metadata: { correlationId: "request-1" },
+            eventId: "event-1",
+            eventName: "probe.ping",
+            payload: { note: "hello" },
+        }
 
-            expect(result.eventName).toBe("")
-            expect(result.envelope).toBeNull()
-            expect(result.cause).toBeInstanceOf(SyntaxError)
+        expect(policy.readEnvelopeText(JSON.stringify(envelope))).toEqual({
+            eventName: "probe.ping",
+            correlationId: "request-1",
+            envelope,
+            cause: null,
         })
     })
 
-    describe("readEventOf", () => {
-        it("builds an event after the envelope and its payload are proven", () => {
-            expect(readEventOf({ eventId: "event-1", payload: { note: "hello" } }, isPingPayload, buildPing)).toEqual(
-                new PingEvent("event-1", { note: "hello" }),
-            )
-        })
+    it.each([
+        {},
+        { metadata: {} },
+        { metadata: { correlationId: 1 } },
+        { metadata: { correlationId: "" } },
+        { metadata: { correlationId: "request\nspoof" } },
+        { metadata: { correlationId: "a".repeat(129) } },
+    ])("refuses missing or unsafe correlation metadata", async (envelope) => {
+        const policy = await build()
 
-        it("refuses a value that is not an envelope without checking its payload", () => {
-            let checked = false
-            const guard = (payload: Record<string, unknown>): payload is PingPayload & Record<string, unknown> => {
-                checked = true
-                return isPingPayload(payload)
-            }
+        expect(policy.readEnvelopeText(JSON.stringify(envelope)).correlationId).toBeNull()
+    })
+})
 
-            expect(readEventOf(null, guard, buildPing)).toBeNull()
-            expect(checked).toBe(false)
+describe("event envelope policies legacy promotion", () => {
+    it("promotes a legacy envelope at its safe event id without changing business fields", async () => {
+        const policy = await build()
+        const legacy = { eventId: "legacy-1", eventName: "probe.ping", payload: { note: "hello" }, causeId: "prior" }
+
+        expect(policy.readEnvelopeText(JSON.stringify(legacy))).toEqual({
+            eventName: "probe.ping",
+            correlationId: "legacy-1",
+            envelope: { ...legacy, metadata: { correlationId: "legacy-1" } },
+            cause: null,
         })
+    })
+
+    it.each([
+        { eventId: "unsafe\nid", eventName: "probe.ping", payload: {} },
+        { eventId: "legacy-1", eventName: 1, payload: {} },
+        { eventId: "legacy-1", eventName: "", payload: {} },
+        { eventId: "legacy-1", eventName: "probe.ping", payload: null },
+        { eventId: "legacy-1", eventName: "probe.ping", payload: [] },
+        { eventId: "legacy-1", eventName: "probe.ping", payload: {}, metadata: null },
+        { eventId: "legacy-1", eventName: "probe.ping", payload: {}, metadata: {} },
+    ])("rejects an unsafe or ambiguous legacy envelope", async (envelope) => {
+        const policy = await build()
+
+        expect(policy.readEnvelopeText(JSON.stringify(envelope)).correlationId).toBeNull()
+    })
+})
 
-        it("refuses an envelope whose payload does not have the event fields", () => {
-            expect(readEventOf({ eventId: "event-1", payload: {} }, isPingPayload, buildPing)).toBeNull()
+describe("event envelope policies JSON shape and decoding", () => {
+    it.each([
+        { value: "null", envelope: null },
+        { value: "42", envelope: 42 },
+        { value: '"provider text"', envelope: "provider text" },
+        { value: "false", envelope: false },
+    ])("refuses valid JSON without an envelope record: $value", async ({ value, envelope }) => {
+        const policy = await build()
+
+        expect(policy.readEnvelopeText(value)).toEqual({
+            eventName: "",
+            correlationId: null,
+            envelope,
+            cause: null,
         })
     })
+
+    it.each([JSON.stringify([]), JSON.stringify({ eventName: 1 })])(
+        "keeps a parsed JSON value without a text event name unnamed",
+        async (value) => {
+            const policy = await build()
+
+            expect(policy.readEnvelopeText(value)).toMatchObject({ eventName: "", cause: null })
+        },
+    )
+
+    it("returns the parse failure for text that is not JSON", async () => {
+        const policy = await build()
+
+        const result = policy.readEnvelopeText("not json")
+
+        expect(result.eventName).toBe("")
+        expect(result.envelope).toBeNull()
+        expect(result.cause).toBeInstanceOf(SyntaxError)
+    })
+})
+
+describe("event envelope policies readEventOf", () => {
+    it("builds an event after the envelope and its payload are proven", async () => {
+        const policy = await build()
+
+        expect(
+            policy.readEventOf({ eventId: "event-1", payload: { note: "hello" } }, isPingPayload, buildPing),
+        ).toEqual(new PingEvent("event-1", { note: "hello" }))
+    })
+
+    it("refuses a value that is not an envelope without checking its payload", async () => {
+        const policy = await build()
+
+        let checked = false
+        const guard = (payload: Record<string, unknown>): payload is PingPayload & Record<string, unknown> => {
+            checked = true
+            return isPingPayload(payload)
+        }
+
+        expect(policy.readEventOf(null, guard, buildPing)).toBeNull()
+        expect(checked).toBe(false)
+    })
+
+    it("refuses an envelope whose payload does not have the event fields", async () => {
+        const policy = await build()
+
+        expect(policy.readEventOf({ eventId: "event-1", payload: {} }, isPingPayload, buildPing)).toBeNull()
+    })
 })

package/templates/be/patterns/event-bus/platform/event-envelope.policy.ts.tpl

@@ -1,5 +1,6 @@
 import type { BaseEvent, ParsedEvent } from "./event-bus.contracts"
 import { isRecord } from "@modules/platform/primitives"
+import { isCorrelationId } from "@modules/platform/logging"
 
 /** What a received envelope carries once its shape is checked: the event id and the payload record. */
 export interface ReadEnvelope {
@@ -14,6 +15,8 @@ export type ReadEnvelopeResult = ReadEnvelope | null
 
 /** What reading the text of a message answers: the event name it carries (empty when none), the parsed value, and the failure when the text is not JSON. */
 export interface ReadEnvelopeText {
+    /** The explicit request context, or null when metadata is missing or malformed. */
+    readonly correlationId: string | null
     /** The event name of the envelope, or an empty text when the value is not an envelope. */
     readonly eventName: string
     /** The parsed value, or null when the text is not JSON. */
@@ -28,14 +31,34 @@ export const readEnvelope = (envelope: unknown): ReadEnvelopeResult =>
         ? { eventId: envelope.eventId, payload: envelope.payload }
         : null
 
+/** Reads current metadata, or promotes an unambiguous legacy envelope rooted at its stable event id. */
+const readCorrelation = (envelope: unknown): Pick<ReadEnvelopeText, "correlationId" | "envelope"> => {
+    if (!isRecord(envelope)) return { correlationId: null, envelope }
+    const metadata = envelope.metadata
+    if (isRecord(metadata) && isCorrelationId(metadata.correlationId))
+        return { correlationId: metadata.correlationId, envelope }
+    if (
+        "metadata" in envelope ||
+        !isCorrelationId(envelope.eventId) ||
+        typeof envelope.eventName !== "string" ||
+        envelope.eventName.length === 0 ||
+        !isRecord(envelope.payload) ||
+        Array.isArray(envelope.payload)
+    ) return { correlationId: null, envelope }
+    return {
+        correlationId: envelope.eventId,
+        envelope: { ...envelope, metadata: { correlationId: envelope.eventId } },
+    }
+}
+
 /** Parses the text of a message and names the event it carries; a text that is not JSON has no name and carries the cause. */
 export const readEnvelopeText = (value: string): ReadEnvelopeText => {
     try {
         const envelope: unknown = JSON.parse(value)
         const eventName = isRecord(envelope) && typeof envelope.eventName === "string" ? envelope.eventName : ""
-        return { eventName, envelope, cause: null }
+        return { eventName, ...readCorrelation(envelope), cause: null }
     } catch (cause) {
-        return { eventName: "", envelope: null, cause }
+        return { eventName: "", envelope: null, correlationId: null, cause }
     }
 }