@servicetitan/journey 3.0.1 → 4.1.0

package/src/__tests__/integrations/request-correlation.test.ts

@@ -0,0 +1,315 @@
+/** @jest-environment jsdom */
+import { baseJourneyDef, useJourneyTestRuntime } from '../../__test-utils__/test-runtime';
+import { journeyStep } from '../../core';
+import { createJourneyRuntime, moduleRuntime } from '../../core/runtime';
+import type { StepHandle } from '../../core/types';
+import { instrumentFetch } from '../../integrations/fetch';
+import { onHttpComplete, type HttpCompleteReport } from '../../integrations/http-report';
+import { captureRequestCorrelation } from '../../integrations/request-correlation';
+import { sendToDatadog } from '../../sinks/datadog';
+
+const emit = jest.fn();
+const addAction = jest.fn();
+const ray = '0123456789abcdef-IAD';
+const epoch = 1_800_000_000_000;
+
+function report(step: StepHandle, overrides: Partial<HttpCompleteReport> = {}): HttpCompleteReport {
+    return {
+        stamp: step.stamp(),
+        status: 500,
+        durationMs: 250,
+        requestKey: '/test',
+        url: 'https://go.servicetitan.com/test?secret=do-not-emit',
+        response: { headers: { 'cf-ray': ray, 'authorization': 'do-not-emit' } },
+        ...overrides,
+    };
+}
+
+function event() {
+    return emit.mock.calls[emit.mock.calls.length - 1][0].journey;
+}
+
+describe('[journey] request correlation', () => {
+    useJourneyTestRuntime(emit);
+    beforeEach(() => {
+        jest.spyOn(Date, 'now').mockReturnValue(epoch);
+        addAction.mockClear();
+        (globalThis as Record<string, unknown>).DD_RUM = { addAction };
+    });
+    afterEach(() => {
+        delete (globalThis as Record<string, unknown>).DD_RUM;
+        jest.restoreAllMocks();
+    });
+
+    test('captures the response before a 5xx synchronously emits, with a usable URL', async () => {
+        await journeyStep(baseJourneyDef, 'save', step => {
+            onHttpComplete(report(step));
+            expect(emit).toHaveBeenCalledTimes(1);
+        });
+        expect(event().outcome).toBe('bad');
+        expect(event().reason).toBe('request-error');
+        expect(event().steps[0].requests).toEqual([
+            {
+                rayId: ray.toLowerCase(),
+                startedAtEpoch: epoch - 250,
+                durationMs: 250,
+                status: 500,
+            },
+        ]);
+        sendToDatadog(emit.mock.calls[0][0]);
+        const context = addAction.mock.calls[0][1];
+        const request = context.journey.steps[0].requests[0];
+        expect(request.request_id).toBe(ray.toLowerCase());
+        expect(context.journey.failed_request_id).toBe(ray.toLowerCase());
+        expect(context.journey.kibana_url).toBe(request.kibana_url);
+        expect(decodeURIComponent(request.kibana_url)).toContain(
+            'Request.RequestId: 0123456789abcdef*'
+        );
+        expect(request.kibana_url).toContain('https://kibana.st.dev/app/discover#/?');
+        expect(JSON.stringify(context)).not.toMatch(/secret|authorization|do-not-emit/);
+        expect(context.journey.tags).toBeUndefined();
+    });
+
+    test.each([
+        { status: 200, durationMs: 5000, reason: 'request-latency' },
+        {
+            status: 400,
+            meta: { httpClientErrorRequests: 'bad' as const },
+            reason: 'request-client-error',
+        },
+    ])('captures before %j is scored', async ({ reason, ...overrides }) => {
+        await journeyStep(baseJourneyDef, 'save', step => onHttpComplete(report(step, overrides)));
+        expect(event().reason).toBe(reason);
+        expect(event().steps[0].requests[0].status).toBe(overrides.status);
+    });
+
+    test.each([200, 400])('does not change the default verdict for status %s', async status => {
+        await journeyStep(baseJourneyDef, 'save', step => {
+            onHttpComplete(report(step, { status }));
+            expect(emit).not.toHaveBeenCalled();
+            step.completeJourney();
+        });
+        expect(event().outcome).toBe('good');
+        expect(event().steps[0].requests).toBeUndefined();
+        expect(event().failedRequest).toBeUndefined();
+    });
+
+    test.each([
+        { status: undefined, response: undefined },
+        { response: { headers: {} } },
+        { response: { headers: { 'cf-ray': 'invalid OR Request.User:*' } } },
+        {
+            response: {
+                getResponseHeader() {
+                    throw new Error('blocked');
+                },
+            },
+        },
+        { url: 'https://third-party.example/test' },
+        { url: 'https://go.servicetitan.com.attacker.invalid/test' },
+        { url: '/test', baseURL: 'https://qa.servicetitan.com' },
+        { response: { headers: { 'cf-ray': ray }, url: 'https://third-party.example/test' } },
+    ])('does not invent a link or change failure scoring for %j', async overrides => {
+        await journeyStep(baseJourneyDef, 'save', step => onHttpComplete(report(step, overrides)));
+        expect(event().outcome).toBe('bad');
+        expect(event().reason).toBe('request-error');
+        expect(event().steps[0].requests).toBeUndefined();
+        expect(event().failedRequest).toBeUndefined();
+    });
+
+    test.each([{ meta: { ignore: true } }, { aborted: true, status: undefined }])(
+        'skips ignored/aborted metadata and preserves outcome for %j',
+        async overrides => {
+            await journeyStep(baseJourneyDef, 'save', step => {
+                onHttpComplete(report(step, overrides));
+                step.completeJourney();
+            });
+            expect(event().outcome).toBe('good');
+            expect(event().steps[0].requests).toBeUndefined();
+        }
+    );
+
+    test('does not record a journey-level ignored endpoint', async () => {
+        const config = { ...baseJourneyDef, endpoints: [{ match: '/test', ignore: true }] };
+        await journeyStep(config, 'save', step => {
+            onHttpComplete(report(step));
+            step.failJourney('different-failure');
+        });
+        expect(event().steps[0].requests).toBeUndefined();
+        expect(event().failedRequest).toBeUndefined();
+    });
+
+    test('captures before a request-specific score closes the journey', async () => {
+        await journeyStep(baseJourneyDef, 'save', step => {
+            onHttpComplete(report(step, { status: 200, stamp: step.stamp(() => 'bad') }));
+        });
+        expect(event().outcome).toBe('bad');
+        expect(event().steps[0].requests).toHaveLength(1);
+    });
+
+    test('bounds requests, keeps errors, and deduplicates early/global jQuery observations', async () => {
+        await journeyStep(baseJourneyDef, 'save', step => {
+            const first = report(step, { status: 400 });
+            captureRequestCorrelation(first);
+            onHttpComplete(first);
+            for (let n = 1; n < 9; n++) {
+                onHttpComplete(
+                    report(step, {
+                        status: 200,
+                        response: { headers: { 'cf-ray': n.toString(16).padStart(16, '0') } },
+                    })
+                );
+            }
+            onHttpComplete(
+                report(step, { response: { headers: { 'cf-ray': 'fedcba9876543210-LAX' } } })
+            );
+        });
+        const { requests, requestsTruncated } = event().steps[0];
+        expect(requests).toHaveLength(5);
+        expect(
+            requests.filter((item: { rayId: string }) => item.rayId === ray.toLowerCase())
+        ).toHaveLength(1);
+        expect(requests[4].rayId).toBe('fedcba9876543210-lax');
+        expect(requestsTruncated).toBe(true);
+    });
+
+    test('an old request cannot attach its ID to a restarted journey', async () => {
+        let old: HttpCompleteReport;
+        await journeyStep(baseJourneyDef, 'old', step => {
+            old = report(step);
+        });
+        moduleRuntime.startJourney(baseJourneyDef);
+        emit.mockClear();
+        onHttpComplete(old!);
+        expect(emit).not.toHaveBeenCalled();
+        await journeyStep(baseJourneyDef, 'new', step => {
+            onHttpComplete(report(step, { response: { headers: {} } }));
+        });
+        expect(event().steps[0].requests).toBeUndefined();
+        expect(event().failedRequest).toBeUndefined();
+    });
+
+    test('routes an explicit stamp to its owning runtime, not a same-named host journey', async () => {
+        const foreignEmit = jest.fn();
+        const foreign = createJourneyRuntime({ sinks: [foreignEmit] });
+        moduleRuntime.startJourney(baseJourneyDef);
+        await foreign.journeyStep(baseJourneyDef, 'foreign-save', step =>
+            onHttpComplete(report(step))
+        );
+        expect(foreignEmit.mock.calls[0][0].journey.steps[0].requests).toHaveLength(1);
+        expect(moduleRuntime.getOpenJourney(baseJourneyDef.name)).toBeDefined();
+        expect(emit).not.toHaveBeenCalled();
+        foreign.reset();
+    });
+
+    test('fetch preserves response identity and captures Headers.get before caller settlement', async () => {
+        const response = { status: 500, headers: new Headers({ 'cf-ray': ray }) };
+        const target = { fetch: jest.fn().mockResolvedValue(response) };
+        const restore = instrumentFetch({ target });
+        try {
+            await journeyStep(baseJourneyDef, 'fetch', async step => {
+                expect(
+                    await target.fetch('https://go.servicetitan.com/test', { stamp: step.stamp() })
+                ).toBe(response);
+                expect(emit).toHaveBeenCalledTimes(1);
+            });
+            expect(event().steps[0].requests).toHaveLength(1);
+        } finally {
+            restore();
+        }
+    });
+
+    test('unrelated concurrent steps receive only their explicitly stamped requests', async () => {
+        let settleFirst!: () => void;
+        const first = journeyStep({ ...baseJourneyDef, name: 'first' }, 'save', async step => {
+            await new Promise<void>(resolve => {
+                settleFirst = resolve;
+            });
+            onHttpComplete(report(step));
+        });
+        await journeyStep({ ...baseJourneyDef, name: 'second' }, 'save', step => {
+            onHttpComplete(
+                report(step, { response: { headers: { 'cf-ray': 'fedcba9876543210-IAD' } } })
+            );
+        });
+        settleFirst();
+        await first;
+        expect(
+            emit.mock.calls.map(call => [
+                call[0].journey.name,
+                call[0].journey.steps[0].requests[0].rayId,
+            ])
+        ).toEqual([
+            ['second', 'fedcba9876543210-iad'],
+            ['first', ray.toLowerCase()],
+        ]);
+    });
+    test('does not blame a previous HTTP response for a later business failure', async () => {
+        await journeyStep(baseJourneyDef, 'save', step => {
+            onHttpComplete(report(step, { status: 200 }));
+            step.failJourney('business-validation');
+        });
+        expect(event().steps[0].requests).toHaveLength(1);
+        expect(event().failedRequest).toBeUndefined();
+        sendToDatadog(emit.mock.calls[0][0]);
+        expect(addAction.mock.calls[0][1].journey.kibana_url).toBeUndefined();
+    });
+
+    test('a successful response never replaces an earlier captured failure', async () => {
+        await journeyStep(baseJourneyDef, 'save', step => {
+            for (let n = 1; n <= 5; n++) {
+                captureRequestCorrelation(
+                    report(step, {
+                        response: { headers: { 'cf-ray': n.toString(16).padStart(16, '0') } },
+                    })
+                );
+            }
+            captureRequestCorrelation(report(step, { status: 200 }));
+            step.failJourney('application-error');
+        });
+        expect(event().steps[0].requests).toHaveLength(5);
+        expect(
+            event().steps[0].requests.every((item: { status: number }) => item.status === 500)
+        ).toBe(true);
+    });
+    test('a later network failure has no top-level link to an earlier successful request', async () => {
+        await journeyStep(baseJourneyDef, 'save', step => {
+            onHttpComplete(report(step, { status: 200 }));
+            onHttpComplete(report(step, { status: undefined, response: undefined }));
+        });
+        expect(event().reason).toBe('request-error');
+        expect(event().failedRequest).toBeUndefined();
+        expect(event().steps[0].requests).toHaveLength(1);
+    });
+
+    test('a slow successful response still gets its failure link when the step history is full', async () => {
+        await journeyStep(baseJourneyDef, 'save', step => {
+            for (let n = 1; n <= 5; n++) {
+                captureRequestCorrelation(
+                    report(step, {
+                        response: { headers: { 'cf-ray': n.toString(16).padStart(16, '0') } },
+                    })
+                );
+            }
+            onHttpComplete(report(step, { status: 200, durationMs: 5000 }));
+        });
+        expect(event().reason).toBe('request-latency');
+        expect(event().failedRequest.rayId).toBe(ray.toLowerCase());
+    });
+
+    test.each(['continue', 'exclude'] as const)(
+        'preserves the request-specific %s policy',
+        async policy => {
+            await journeyStep(baseJourneyDef, 'save', step => {
+                onHttpComplete(report(step, { stamp: step.stamp(() => policy) }));
+                if (policy === 'continue') {
+                    expect(emit).not.toHaveBeenCalled();
+                    step.completeJourney();
+                }
+            });
+            expect(event().outcome).toBe(policy === 'continue' ? 'good' : 'excluded');
+            expect(event().failedRequest).toBeUndefined();
+            expect(event().steps[0].requests).toBeUndefined();
+        }
+    );
+});

package/src/__tests__/sinks/kibana.test.ts

@@ -0,0 +1,110 @@
+/** @jest-environment jsdom */
+import { sanitizeJourneyEvent } from '../../core/sanitize';
+import { MAX_JOURNEY_CORRELATED_REQUESTS } from '../../core/request-correlation';
+import type { JourneyEvent, JourneyRequestEvent } from '../../core/types';
+import { requestLogsUrl } from '../../sinks/kibana';
+
+const request: JourneyRequestEvent = {
+    rayId: '0123456789abcdef-IAD',
+    startedAtEpoch: Date.parse('2026-09-17T18:00:00.000Z'),
+    durationMs: 2000,
+    status: 500,
+};
+
+function event(outcome: JourneyEvent['journey']['outcome'] = 'bad'): JourneyEvent {
+    return {
+        journey: {
+            name: 'test',
+            team: 'test',
+            group: 'test',
+            service: 'test',
+            outcome,
+            durationMs: 2000,
+            steps: [
+                { name: 'save', startMs: 0, durationMs: 2000, outcome: 'bad', requests: [request] },
+            ],
+        },
+    };
+}
+
+describe('[journey] request logs link', () => {
+    test('uses the verified production view and an absolute request window', () => {
+        const url = new URL(requestLogsUrl(request)!);
+        expect(url.origin).toBe('https://kibana.st.dev');
+        expect(url.pathname).toBe('/app/discover');
+        const params = new URLSearchParams(url.hash.slice(3));
+        expect(params.get('_g')).toBe(
+            "(refreshInterval:(pause:!t,value:0),time:(from:'2026-09-17T17:59:00.000Z',to:'2026-09-17T18:01:02.000Z'))"
+        );
+        expect(params.get('_a')).toBe(
+            "(dataSource:(type:dataView,dataViewId:'894110ed-c22d-449c-9dc2-c4816f08712a'),query:(language:kuery,query:'Request.RequestId: 0123456789abcdef*'))"
+        );
+        expect(url.href).not.toContain('IAD');
+    });
+
+    test.each([
+        { rayId: "0123456789abcdef') OR *" },
+        { rayId: 'https://attacker.example' },
+        { rayId: 'a'.repeat(1000) },
+        { rayId: '0123456789abcde' },
+        { rayId: '0123456789abcdef-INVALID' },
+        { startedAtEpoch: NaN },
+        { startedAtEpoch: Infinity },
+        { startedAtEpoch: -1 },
+        { startedAtEpoch: 8.64e15 },
+        { durationMs: -1 },
+        { durationMs: Infinity },
+        { status: 0 },
+        { status: 600 },
+        { status: 200.5 },
+    ])('rejects invalid correlation %j', invalid => {
+        expect(requestLogsUrl({ ...request, ...invalid })).toBeUndefined();
+        const payload = event();
+        payload.journey.steps[0].requests = [{ ...request, ...invalid }];
+        expect(sanitizeJourneyEvent(payload).journey.steps[0].requests).toBeUndefined();
+    });
+
+    test('sanitizes correlation by allowlist, not the metric-tag string normalizer', () => {
+        const payload = event();
+        payload.journey.steps[0].requests = [
+            {
+                ...request,
+                url: '/test?password=secret',
+                headers: { authorization: 'secret' },
+            } as JourneyRequestEvent,
+        ];
+        expect(sanitizeJourneyEvent(payload).journey.steps[0].requests).toEqual([
+            { ...request, rayId: request.rayId.toLowerCase() },
+        ]);
+    });
+
+    test.each(['good', 'excluded'] as const)('omits correlation on %s events', outcome => {
+        expect(sanitizeJourneyEvent(event(outcome)).journey.steps[0].requests).toBeUndefined();
+    });
+
+    test('caps the event payload and preserves links on the last failing step', () => {
+        const payload = event();
+        payload.journey.steps = Array.from({ length: 50 }, (_, index) => ({
+            ...payload.journey.steps[0],
+            name: `step-${index}`,
+        }));
+        const steps = sanitizeJourneyEvent(payload).journey.steps;
+        expect(steps.reduce((count, step) => count + (step.requests?.length ?? 0), 0)).toBe(
+            MAX_JOURNEY_CORRELATED_REQUESTS
+        );
+        expect(steps[0].requestsTruncated).toBe(true);
+        expect(steps[49].requests).toHaveLength(1);
+    });
+    test('validates the top-level failure request and strips it from non-bad events', () => {
+        const payload = event();
+        payload.journey.failedRequest = { ...request, rayId: "0123456789abcdef') OR *" };
+        expect(sanitizeJourneyEvent(payload).journey.failedRequest).toBeUndefined();
+        payload.journey.failedRequest = request;
+        expect(sanitizeJourneyEvent(payload).journey.failedRequest).toEqual({
+            ...request,
+            rayId: request.rayId.toLowerCase(),
+        });
+        payload.journey.outcome = 'good';
+        expect(sanitizeJourneyEvent(payload).journey.failedRequest).toBeUndefined();
+    });
+});

package/src/core/api.ts

@@ -5,6 +5,7 @@ import type {
     JourneyHandle,
     JourneyStepOptions,
     JourneyStepTarget,
+    SerializedJourneyState,
     StepHandle,
     StepRecord,
     TagValue,
@@ -157,3 +158,21 @@ export function defineJourney(config: JourneyDef): JourneyHandle {
         },
     };
 }
+
+/**
+ * Snapshot an open journey for cross-page transfer (e.g. into a cookie). Does
+ * NOT close the journey. Returns `null` when no journey is open under `name`.
+ */
+export function serializeJourneyState(name: string): SerializedJourneyState | null {
+    return moduleRuntime.serializeJourneyState(name);
+}
+
+/**
+ * Rehydrate a serialized journey onto this runtime. Returns `true` when the
+ * journey is now open; `false` when it exhausted its budget in transit (a
+ * `bad` `journey-timeout` event is emitted) or when a journey under the
+ * same name is already open.
+ */
+export function restoreJourney(serialized: SerializedJourneyState, config: JourneyDef): boolean {
+    return moduleRuntime.restoreJourney(serialized, config) !== null;
+}

package/src/core/index.ts

@@ -8,6 +8,8 @@ export {
     journeyStep,
     reportBackendRequest,
     resolveStamp,
+    restoreJourney,
+    serializeJourneyState,
     setJourneyTags,
     singleInFlightJourneyStep,
 } from './api';
@@ -18,12 +20,14 @@ export {
 export type {
     JourneyDef,
     JourneyEvent,
+    JourneyRequestEvent,
     JourneyHandle,
     JourneyNameLike,
     JourneySink,
     JourneyStepEvent,
     JourneyStepOptions,
     JourneyStepTarget,
+    SerializedJourneyState,
     StepHandle,
     TagValue,
 } from './types';

package/src/core/persist.ts

@@ -0,0 +1,131 @@
+import {
+    clampMaxSteps,
+    finiteSlowRequestMs,
+    finiteTimeoutMs,
+    MAX_ATTRIBUTE_KEYS,
+    MAX_TAG_KEYS,
+    resolveJourneyTimeoutMs,
+} from './limits';
+import { assignRecord, emptyRecord } from './sanitize';
+import { bindJourneyEngine, freezeJourneyDef, type JourneyRuntime } from './runtime';
+import {
+    JOURNEY_ENGINE,
+    type JourneyDef,
+    type JourneyState,
+    type SerializedJourneyState,
+    type StepRecord,
+} from './types';
+
+/**
+ * @internal Project an open {@link JourneyState} into a plain, JSON-safe
+ * {@link SerializedJourneyState} that can ride a cookie across page navigations.
+ * The step projection mirrors `finish()`; `startedAt` (a `performance.now()`
+ * monotonic stamp) is bridged to a wall-clock epoch so it survives the page
+ * load where `performance.now()` resets.
+ */
+export function projectJourneyState(journey: JourneyState): SerializedJourneyState {
+    const steps = journey.steps.map(s => ({
+        name: s.name,
+        startMs: Math.round(s.startedAt - journey.startedAt),
+        durationMs: s.durationMs || Math.round(globalThis.performance.now() - s.startedAt),
+        outcome: s.outcome,
+        ...(s.reason ? { reason: s.reason } : {}),
+        ...(s.httpStatus !== undefined ? { httpStatus: s.httpStatus } : {}),
+        // Attributes are raw here — final emission sanitization happens in finish().
+        ...(Object.keys(s.attributes).length ? { attributes: { ...s.attributes } } : {}),
+    }));
+
+    const startedAtEpoch = Date.now() - (globalThis.performance.now() - journey.startedAt);
+    // Coerce any non-null st_journey_id tag to a string so a numeric/boolean id survives the round-trip.
+    const stJourneyId =
+        journey.tags.st_journey_id != null ? String(journey.tags.st_journey_id) : '';
+
+    return {
+        stJourneyId,
+        startedAtEpoch,
+        // Open journeys are never 'excluded' — that verdict is only set inside finish().
+        verdict: journey.verdict === 'bad' ? 'bad' : 'good',
+        reason: journey.reason,
+        steps,
+        tags: { ...journey.tags },
+    };
+}
+
+/**
+ * @internal Rehydrate a {@link SerializedJourneyState} into a live
+ * {@link JourneyState} bound to the supplied runtime. `startedAt` is rebased
+ * from the wall-clock epoch back to a `performance.now()` monotonic stamp,
+ * `StepRecord[]` is rebuilt with re-linked circular references, and the
+ * `JOURNEY_ENGINE` hook is re-bound so HTTP attribution works on the new page.
+ */
+export function deserializeJourneyState(
+    serialized: SerializedJourneyState,
+    config: JourneyDef,
+    api: JourneyRuntime,
+    defaultJourneyIdleMs: number
+): JourneyState {
+    const tags = emptyRecord();
+    // Caller config tags win; serialized tags fill the rest (incl. st_journey_id).
+    assignRecord(tags, serialized.tags, MAX_TAG_KEYS);
+    assignRecord(tags, config.tags, MAX_TAG_KEYS);
+    if (serialized.stJourneyId && tags.st_journey_id === undefined) {
+        tags.st_journey_id = serialized.stJourneyId;
+    }
+
+    const snapshot = freezeJourneyDef(config, tags);
+    const timeout = resolveJourneyTimeoutMs(snapshot.timeoutMs, defaultJourneyIdleMs);
+
+    const startedAt = globalThis.performance.now() - (Date.now() - serialized.startedAtEpoch);
+
+    const journey: JourneyState = {
+        config: snapshot,
+        name: snapshot.name,
+        team: snapshot.team,
+        group: snapshot.group,
+        service: snapshot.service,
+        verdict: serialized.verdict === 'bad' ? 'bad' : 'good',
+        startedAt,
+        timeoutMs: timeout.ms,
+        timeoutExplicit: timeout.explicit,
+        stepTimeoutMs:
+            snapshot.stepTimeoutMs !== undefined
+                ? finiteTimeoutMs(snapshot.stepTimeoutMs)
+                : undefined,
+        reason: serialized.reason,
+        steps: [],
+        expected: snapshot.expected ? [...snapshot.expected] : null,
+        tags,
+        slowRequestMs: finiteSlowRequestMs(snapshot.slowRequestMs),
+        endpoints: snapshot.endpoints,
+        timer: null,
+        closed: false,
+        maxSteps: snapshot.maxSteps !== undefined ? clampMaxSteps(snapshot.maxSteps) : undefined,
+    };
+
+    // Rebuild StepRecord[] — re-link the circular `step.journey` reference and rebase `startedAt` from the offset.
+    for (const s of serialized.steps) {
+        const step: StepRecord = {
+            name: s.name,
+            startedAt: journey.startedAt + s.startMs,
+            durationMs: s.durationMs,
+            outcome: s.outcome,
+            attributes: emptyRecord(),
+            journey,
+        };
+        if (s.reason !== undefined) {
+            step.reason = s.reason;
+        }
+        if (s.httpStatus !== undefined) {
+            step.httpStatus = s.httpStatus;
+        }
+        if (s.attributes) {
+            assignRecord(step.attributes, s.attributes, MAX_ATTRIBUTE_KEYS);
+        }
+        journey.steps.push(step);
+    }
+
+    // Re-bind the engine so HTTP attribution / fail-fast works on this page.
+    journey[JOURNEY_ENGINE] = bindJourneyEngine(api, journey, api.shouldIgnoreRequest);
+
+    return journey;
+}

package/src/core/request-correlation.ts

@@ -0,0 +1,32 @@
+import type { JourneyRequestEvent } from './types';
+
+export const MAX_CORRELATED_REQUESTS = 5;
+export const MAX_JOURNEY_CORRELATED_REQUESTS = 20;
+
+/** Only allow a Cloudflare Ray ID and bounded numeric response metadata onto the wire. */
+export function sanitizeRequestCorrelation(
+    value: JourneyRequestEvent
+): JourneyRequestEvent | undefined {
+    if (
+        !value ||
+        typeof value.rayId !== 'string' ||
+        !/^[a-f0-9]{16}(?:-[a-z]{3})?$/i.test(value.rayId) ||
+        !Number.isFinite(value.startedAtEpoch) ||
+        value.startedAtEpoch <= 0 ||
+        value.startedAtEpoch > 8.64e15 - 2 * 86_400_000 ||
+        !Number.isFinite(value.durationMs) ||
+        value.durationMs < 0 ||
+        value.durationMs > 86_400_000 ||
+        !Number.isInteger(value.status) ||
+        value.status < 100 ||
+        value.status > 599
+    ) {
+        return undefined;
+    }
+    return {
+        rayId: value.rayId.toLowerCase(),
+        startedAtEpoch: Math.round(value.startedAtEpoch),
+        durationMs: Math.round(value.durationMs),
+        status: value.status,
+    };
+}