@servicetitan/journey 2.0.0 → 3.0.0

package/src/core/runtime.ts

@@ -1,70 +1,171 @@
 import {
-    longestEndpointMatch,
+    getAutoAttributeRequests as getSharedAutoAttributeRequests,
+    getHttpAbortedRequestsPolicy as getSharedHttpAbortedRequestsPolicy,
+    getHttpClientErrorRequestsPolicy as getSharedHttpClientErrorRequestsPolicy,
+    getSharedSlowRequests,
+    isJourneyDebugEnabled,
+} from '../global';
+import { isCanceledError } from './abort-error';
+import {
+    resolveEndpointPolicy,
     sortEndpointsByLongestMatch,
-    type AppRequestTimeouts,
-} from '../endpoint-policy';
-import { JourneyStepTag } from './step-tag';
-import type {
-    JourneyDef,
-    JourneyEvent,
-    JourneySink,
-    JourneyState,
-    JourneyStepEvent,
-    JourneyStepOptions,
-    JourneyStepRef,
-    JourneyStepTarget,
-    Outcome,
-    StepHandle,
-    StepRecord,
-    TagValue,
+    type SlowRequestConfig,
+} from './endpoint-policy';
+import {
+    clampMaxSteps,
+    DEFAULT_MAX_STEPS,
+    DEFAULT_JOURNEY_IDLE_MS,
+    finiteSlowRequestMs,
+    finiteTimeoutMs,
+    MAX_ATTRIBUTED_REQUEST_KEYS,
+    MAX_TAG_KEYS,
+    resolveJourneyTimeoutMs,
+} from './limits';
+import { assignRecord, emptyRecord, sanitizeJourneyEvent, setSafeAttribute } from './sanitize';
+import { JourneyStepStamp, resolveStampOpts } from './step-tag';
+import type { RequestPolicyConfig } from './request-policy';
+import {
+    JOURNEY_ENGINE,
+    type JourneyDef,
+    type JourneyEngine,
+    type JourneyEvent,
+    type JourneyNameLike,
+    type JourneySink,
+    type JourneyState,
+    type JourneyStepEvent,
+    type JourneyStepOptions,
+    type JourneyStepTarget,
+    type Outcome,
+    type StepHandle,
+    type StepRecord,
+    type TagValue,
 } from './types';
 
-const DEFAULT_REQUEST_TIMEOUTS: AppRequestTimeouts = { defaultMs: 4_000, endpoints: [] };
+const DEFAULT_SLOW_REQUESTS: SlowRequestConfig = { defaultMs: 4_000, endpoints: [] };
 
 const noopStep: StepHandle = {
-    name: null,
+    journeyName: null,
     setAttribute() {},
     setTags() {},
-    complete() {},
-    fail() {},
-    tag: () => ({}),
+    completeJourney() {},
+    failJourney() {},
+    stamp: () => undefined,
 };
 
-function toName(target: string | { readonly name: string }): string {
-    return typeof target === 'string' ? target : target.name;
+function toName(target: JourneyNameLike): string {
+    if (typeof target === 'string') {
+        return target;
+    }
+    return 'config' in target ? target.config.name : target.name;
 }
 
 /** @internal Private — not part of the public package API. */
 export interface JourneyRuntimeOptions {
-    /** Initial sinks. Defaults to `[]` — package bootstrap installs Datadog on the default runtime. */
+    /**
+     * DevTools label for this engine copy (`__stJourney.getDebugState().runtimes`).
+     * Auto-assigned `runtime-N` from the current `__stJourney` registration count
+     * when omitted at `registerJourneyRuntime`.
+     */
+    id?: string;
+    /** Initial sinks. Defaults to `[]` — package bootstrap installs Datadog on the module runtime. */
     sinks?: readonly JourneySink[];
-    requestTimeouts?: AppRequestTimeouts;
+    slowRequests?: SlowRequestConfig;
+    /** Cap recorded steps; default 50. */
+    maxSteps?: number;
+    /** Default timeout when JourneyDef.timeoutMs is omitted. 0 disables idle countdown. */
+    defaultJourneyIdleMs?: number;
+}
+
+/** @internal Read-only snapshot for DevTools (`__stJourney.getDebugState`; empty unless debugging). */
+export interface JourneyRuntimeDebugSnapshot {
+    id: string;
+    openJourneys: readonly {
+        name: string;
+        team: string;
+        group: string;
+        service: string;
+        verdict: Outcome;
+        reason: string | null;
+        tags: Record<string, TagValue>;
+        stepsInFlight: readonly string[];
+        steps: readonly {
+            name: string;
+            outcome: 'good' | 'bad';
+            durationMs: number;
+            reason?: string;
+            attributedRequestKeys?: readonly string[];
+        }[];
+    }[];
+    activeStep: { journey: string; name: string } | null;
+    /** Which shared policy knobs this runtime overrode (false = inherit global). */
+    policyOverlay: {
+        slowRequests: boolean;
+        httpAbortedRequests: boolean;
+        httpClientErrorRequests: boolean;
+        autoAttributeRequests: boolean;
+    };
+}
+
+function freezeJourneyDef(config: JourneyDef, tags: Record<string, TagValue>): JourneyDef {
+    const endpoints = sortEndpointsByLongestMatch(config.endpoints);
+    return Object.freeze({
+        ...config,
+        timeoutMs: config.timeoutMs !== undefined ? finiteTimeoutMs(config.timeoutMs) : undefined,
+        stepTimeoutMs:
+            config.stepTimeoutMs !== undefined ? finiteTimeoutMs(config.stepTimeoutMs) : undefined,
+        slowRequestMs: finiteSlowRequestMs(config.slowRequestMs),
+        maxSteps: config.maxSteps !== undefined ? clampMaxSteps(config.maxSteps) : undefined,
+        endpoints: endpoints ? Object.freeze([...endpoints]) : undefined,
+        expected: config.expected ? Object.freeze([...config.expected]) : undefined,
+        tags: Object.freeze({ ...tags }),
+    });
 }
 
 /**
  * @internal Private — not part of the public package API.
  * Isolated journey engine (open journeys, ambient steps, sinks, request thresholds).
  * App code should keep using free helpers (`defineJourney`, `journeyStep`, …) — they
- * bind to the process default runtime. Prefer `resetJourney()` in tests.
+ * bind to the module runtime. Prefer `resetJourney()` in tests.
  */
 export interface JourneyRuntime {
-    getRequestTimeouts(): AppRequestTimeouts;
-    setRequestTimeouts(next: AppRequestTimeouts): void;
+    /** DevTools id for this engine copy. Auto `runtime-N` when registered without an id. */
+    readonly id: string;
+    getSlowRequests(): SlowRequestConfig;
+    setSlowRequests(next: SlowRequestConfig): void;
+    getMaxSteps(): number;
+    setMaxSteps(next: number): void;
+    getDefaultJourneyIdleMs(): number;
+    setDefaultJourneyIdleMs(next: number): void;
 
     setSinks(next: readonly JourneySink[]): void;
+    /** First `configureJourney({ sinks })` on this runtime wins. Returns false if already set. */
+    trySetConfiguredSinks(next: readonly JourneySink[]): boolean;
     addSink(sink: JourneySink): void;
     emit(payload: JourneyEvent): void;
 
+    setPolicyOverlay(next: {
+        slowRequests?: SlowRequestConfig;
+        httpAbortedRequests?: RequestPolicyConfig;
+        httpClientErrorRequests?: RequestPolicyConfig;
+        autoAttributeRequests?: boolean;
+    }): void;
+    getAutoAttributeRequests(): boolean;
+    getHttpAbortedRequestsPolicy(): RequestPolicyConfig;
+    getHttpClientErrorRequestsPolicy(): RequestPolicyConfig;
+
     getOpenJourney(name: string): JourneyState | undefined;
-    firstOpenJourney(names: readonly string[]): string | null;
+    /** @internal DevTools snapshot of open journeys / ambient step. */
+    getDebugSnapshot(): JourneyRuntimeDebugSnapshot;
+    firstOpenJourneyName(names: readonly string[]): string | null;
     setJourneyTags(name: string | null, tags: Record<string, TagValue>): void;
-    startJourney(def: JourneyDef): void;
-    failJourneyNow(journey: JourneyState, reason: string): void;
-    failJourney(name: string, reason: string): void;
+    startJourney(config: JourneyDef): void;
+    failJourney(journey: JourneyState, reason: string): void;
     completeJourney(name: string | null, tags?: Record<string, TagValue>): void;
-    excludeJourney(name: string): void;
+    completeJourneyState(journey: JourneyState, tags?: Record<string, TagValue>): void;
+    excludeJourney(journey: JourneyState): void;
+    updateOpenJourney(config: JourneyDef): void;
 
-    activeJourneyStep(): JourneyStepRef | null;
+    activeJourneyStep(): StepRecord | null;
     journeyStep<T>(
         journey: JourneyStepTarget,
         stepName: string,
@@ -79,30 +180,71 @@ export interface JourneyRuntime {
     ): Promise<T>;
 
     reportBackendRequest(
-        step: JourneyStepRef | undefined,
+        step: StepRecord | undefined,
         status: number | undefined,
         durationMs: number,
         requestKey: string
     ): void;
+    /** True when this request key is ignored for the step's journey (never changes verdict). */
+    shouldIgnoreRequest(journey: JourneyState, key: string): boolean;
 
     /** Close open journeys, clear ambient steps, restore default timeouts/sinks. */
     reset(options?: JourneyRuntimeOptions): void;
 }
 
+function bindJourneyEngine(
+    api: JourneyRuntime,
+    journey: JourneyState,
+    shouldIgnoreRequest: (target: JourneyState, key: string) => boolean
+): JourneyEngine {
+    return {
+        failJourney(reason) {
+            api.failJourney(journey, reason);
+        },
+        exclude() {
+            api.excludeJourney(journey);
+        },
+        shouldIgnoreRequest(key) {
+            return shouldIgnoreRequest(journey, key);
+        },
+        reportBackendRequest(step, status, durationMs, requestKey) {
+            api.reportBackendRequest(step, status, durationMs, requestKey);
+        },
+        getHttpAbortedRequestsPolicy() {
+            return api.getHttpAbortedRequestsPolicy();
+        },
+        getHttpClientErrorRequestsPolicy() {
+            return api.getHttpClientErrorRequestsPolicy();
+        },
+    };
+}
+
 /**
  * @internal Private — not part of the public package API.
  * Build an isolated engine. Rarely needed — apps use the default via free helpers.
  */
 export function createJourneyRuntime(options: JourneyRuntimeOptions = {}): JourneyRuntime {
+    let id = typeof options.id === 'string' && options.id !== '' ? options.id : '';
     const journeys = new Map<string, JourneyState>();
     const inFlight = new Set<StepRecord>();
     let sinks: JourneySink[] = [...(options.sinks ?? [])];
-    let requestTimeouts: AppRequestTimeouts = {
-        defaultMs: options.requestTimeouts?.defaultMs ?? DEFAULT_REQUEST_TIMEOUTS.defaultMs,
+    let sinksConfigured = false;
+    let overlay: {
+        slowRequests?: SlowRequestConfig;
+        httpAbortedRequests?: RequestPolicyConfig;
+        httpClientErrorRequests?: RequestPolicyConfig;
+        autoAttributeRequests?: boolean;
+    } = {};
+    let slowRequests: SlowRequestConfig = {
+        defaultMs: options.slowRequests?.defaultMs ?? DEFAULT_SLOW_REQUESTS.defaultMs,
         endpoints: sortEndpointsByLongestMatch(
-            options.requestTimeouts?.endpoints ?? DEFAULT_REQUEST_TIMEOUTS.endpoints
+            options.slowRequests?.endpoints ?? DEFAULT_SLOW_REQUESTS.endpoints
         ),
     };
+    let maxSteps = clampMaxSteps(options.maxSteps ?? DEFAULT_MAX_STEPS);
+    let defaultJourneyIdleMs = finiteTimeoutMs(
+        options.defaultJourneyIdleMs ?? DEFAULT_JOURNEY_IDLE_MS
+    );
 
     function getInFlightSteps(journey: JourneyState): StepRecord[] {
         const out: StepRecord[] = [];
@@ -122,6 +264,18 @@ export function createJourneyRuntime(options: JourneyRuntimeOptions = {}): Journ
         inFlight.delete(step);
     }
 
+    function releaseInFlightSteps(journey: JourneyState): void {
+        for (const step of [...inFlight]) {
+            if (step.journey !== journey) {
+                continue;
+            }
+            if (step.durationMs === 0) {
+                step.durationMs = Math.round(globalThis.performance.now() - step.startedAt);
+            }
+            inFlight.delete(step);
+        }
+    }
+
     function clearCountdown(journey: JourneyState): void {
         if (journey.timer != null) {
             clearTimeout(journey.timer);
@@ -130,9 +284,10 @@ export function createJourneyRuntime(options: JourneyRuntimeOptions = {}): Journ
     }
 
     function emit(payload: JourneyEvent): void {
+        const safePayload = sanitizeJourneyEvent(payload);
         for (const sink of sinks) {
             try {
-                sink(payload);
+                sink(safePayload);
             } catch {
                 // One sinking throw must not block the remaining sinks.
             }
@@ -144,19 +299,16 @@ export function createJourneyRuntime(options: JourneyRuntimeOptions = {}): Journ
             return;
         }
         journey.closed = true;
-        journeys.delete(journey.name);
-        clearCountdown(journey);
-
-        for (const step of getInFlightSteps(journey)) {
-            if (step.durationMs === 0) {
-                step.durationMs = Math.round(globalThis.performance.now() - step.startedAt);
-            }
+        if (journeys.get(journey.name) === journey) {
+            journeys.delete(journey.name);
         }
+        clearCountdown(journey);
+        releaseInFlightSteps(journey);
 
         let finalReason = journey.reason ?? reason;
         let finalOutcome = outcome;
         const durationMs = Math.round(globalThis.performance.now() - journey.startedAt);
-        if (journey.timeoutMs > 0 && durationMs > journey.timeoutMs) {
+        if (journey.timeoutExplicit && journey.timeoutMs > 0 && durationMs > journey.timeoutMs) {
             finalOutcome = 'bad';
             finalReason = finalReason ?? 'journey-timeout';
         }
@@ -168,7 +320,7 @@ export function createJourneyRuntime(options: JourneyRuntimeOptions = {}): Journ
             outcome: s.outcome,
             ...(s.reason ? { reason: s.reason } : {}),
             ...(s.httpStatus !== undefined ? { httpStatus: s.httpStatus } : {}),
-            ...(Object.keys(s.attributes).length ? { attributes: s.attributes } : {}),
+            ...(Object.keys(s.attributes).length ? { attributes: { ...s.attributes } } : {}),
         }));
 
         emit({
@@ -178,48 +330,47 @@ export function createJourneyRuntime(options: JourneyRuntimeOptions = {}): Journ
                 group: journey.group,
                 service: journey.service,
                 outcome: finalOutcome,
-                ...(finalOutcome === 'bad' && finalReason ? { reason: finalReason } : {}),
+                ...(finalReason ? { reason: finalReason } : {}),
                 durationMs,
                 steps,
                 ...(journey.expected ? { expected: journey.expected } : {}),
-                ...(Object.keys(journey.tags).length ? { tags: journey.tags } : {}),
+                ...(Object.keys(journey.tags).length ? { tags: { ...journey.tags } } : {}),
             },
         });
     }
 
-    function armCountdown(journey: JourneyState): void {
-        if (journey.timeoutMs <= 0) {
+    function armCountdown(journey: JourneyState, delayMs: number = journey.timeoutMs): void {
+        if (delayMs <= 0) {
             return;
         }
         journey.timer = setTimeout(() => {
-            finish(journey, 'bad', 'journey-timeout');
-        }, journey.timeoutMs);
+            if (journey.timeoutExplicit) {
+                finish(journey, 'bad', 'journey-timeout');
+                return;
+            }
+            finish(journey, journey.verdict === 'bad' ? 'bad' : 'excluded', 'journey-idle-timeout');
+        }, delayMs);
     }
 
-    function resolveRequestTimeoutMs(journey: JourneyState, key: string): number {
-        const own = longestEndpointMatch(journey.endpoints, key);
-        if (own?.timeoutMs) {
-            return own.timeoutMs;
-        }
-
-        const app = longestEndpointMatch(requestTimeouts.endpoints, key);
-        if (app?.timeoutMs) {
-            return app.timeoutMs;
-        }
-
-        if (journey.requestTimeoutMs != null) {
-            return journey.requestTimeoutMs;
-        }
-
-        return requestTimeouts.defaultMs;
+    function effectiveSlowRequests(): SlowRequestConfig {
+        return overlay.slowRequests ?? getSharedSlowRequests() ?? slowRequests;
     }
 
     function shouldIgnoreRequest(journey: JourneyState, key: string): boolean {
-        const own = longestEndpointMatch(journey.endpoints, key);
-        if (own) {
-            return own.ignore === true;
+        return resolveEndpointPolicy(journey, effectiveSlowRequests(), key).ignore;
+    }
+
+    function trackAttributedKey(step: StepRecord, requestKey: string): void {
+        if (!requestKey) {
+            return;
+        }
+        step.attributedRequestKeys ??= [];
+        if (step.attributedRequestKeys.length >= MAX_ATTRIBUTED_REQUEST_KEYS) {
+            return;
+        }
+        if (!step.attributedRequestKeys.includes(requestKey)) {
+            step.attributedRequestKeys.push(requestKey);
         }
-        return longestEndpointMatch(requestTimeouts.endpoints, key)?.ignore === true;
     }
 
     function resolveJourneyName(journey: JourneyStepTarget): string | null {
@@ -227,58 +378,178 @@ export function createJourneyRuntime(options: JourneyRuntimeOptions = {}): Journ
             return null;
         }
         if (typeof journey === 'string' || !Array.isArray(journey)) {
-            return toName(journey as string | { readonly name: string });
+            return toName(journey as JourneyNameLike);
+        }
+        return api.firstOpenJourneyName(journey.map(toName));
+    }
+
+    function configFromTarget(target: JourneyNameLike): JourneyDef | undefined {
+        if (typeof target === 'string') {
+            return undefined;
+        }
+        if ('config' in target && target.config != null && typeof target.config === 'object') {
+            return target.config;
+        }
+        const rec = target as {
+            name?: unknown;
+            team?: unknown;
+            group?: unknown;
+            service?: unknown;
+        };
+        if (
+            typeof rec.name === 'string' &&
+            typeof rec.team === 'string' &&
+            typeof rec.group === 'string' &&
+            typeof rec.service === 'string'
+        ) {
+            return target as JourneyDef;
+        }
+        return undefined;
+    }
+
+    function maybeAutoStart(target: JourneyStepTarget): void {
+        if (target == null || typeof target === 'string' || Array.isArray(target)) {
+            return;
+        }
+        const def = configFromTarget(target as JourneyNameLike);
+        if (def && !api.getOpenJourney(def.name)) {
+            api.startJourney(def);
         }
-        return api.firstOpenJourney(journey.map(toName));
     }
 
     function createStepHandle(journeyName: string, step: StepRecord): StepHandle {
         return {
-            name: journeyName,
+            journeyName,
             setAttribute(key, value) {
-                step.attributes[key] = value;
+                setSafeAttribute(step.attributes, key, value);
             },
             setTags(tags) {
-                api.setJourneyTags(journeyName, tags);
+                if (step.journey.closed) {
+                    return;
+                }
+                assignRecord(step.journey.tags, tags, MAX_TAG_KEYS);
             },
-            complete(tags) {
-                api.completeJourney(journeyName, tags);
+            completeJourney(tags) {
+                api.completeJourneyState(step.journey, tags);
             },
-            fail(reason) {
-                api.failJourney(journeyName, reason);
+            failJourney(reason) {
+                api.failJourney(step.journey, reason);
             },
-            // Box in JourneyStepTag — raw StepRecord is circular and blows jQuery/axios deep-merge.
-            tag: () => ({ journeyStep: new JourneyStepTag(step) }),
+            // Box in JourneyStepStamp — raw StepRecord is circular and blows jQuery/axios deep-merge.
+            stamp: scoreOrOpts => new JourneyStepStamp(step, resolveStampOpts(scoreOrOpts)),
         };
     }
 
     const api: JourneyRuntime = {
-        getRequestTimeouts() {
-            return requestTimeouts;
+        get id() {
+            return id;
+        },
+        set id(next: string) {
+            id = next;
+        },
+        getSlowRequests() {
+            return effectiveSlowRequests();
         },
 
-        setRequestTimeouts(next) {
-            requestTimeouts = {
+        setSlowRequests(next) {
+            slowRequests = {
                 ...next,
                 endpoints: sortEndpointsByLongestMatch(next.endpoints),
             };
         },
 
+        getMaxSteps() {
+            return maxSteps;
+        },
+
+        setMaxSteps(next) {
+            maxSteps = clampMaxSteps(next);
+        },
+
+        getDefaultJourneyIdleMs() {
+            return defaultJourneyIdleMs;
+        },
+
+        setDefaultJourneyIdleMs(next) {
+            defaultJourneyIdleMs = finiteTimeoutMs(next);
+        },
+
         setSinks(next) {
             sinks = [...next];
         },
 
+        trySetConfiguredSinks(next) {
+            if (sinksConfigured) {
+                return false;
+            }
+            sinks = [...next];
+            sinksConfigured = true;
+            return true;
+        },
+
         addSink(sink) {
             sinks.push(sink);
         },
 
         emit,
 
+        setPolicyOverlay(next) {
+            overlay = { ...overlay, ...next };
+        },
+
+        getAutoAttributeRequests() {
+            if (overlay.autoAttributeRequests !== undefined) {
+                return overlay.autoAttributeRequests;
+            }
+            return getSharedAutoAttributeRequests();
+        },
+
+        getHttpAbortedRequestsPolicy() {
+            return overlay.httpAbortedRequests ?? getSharedHttpAbortedRequestsPolicy();
+        },
+
+        getHttpClientErrorRequestsPolicy() {
+            return overlay.httpClientErrorRequests ?? getSharedHttpClientErrorRequestsPolicy();
+        },
+
         getOpenJourney(name) {
             return journeys.get(name);
         },
 
-        firstOpenJourney(names) {
+        getDebugSnapshot() {
+            const active = api.activeJourneyStep();
+            return {
+                id: api.id,
+                openJourneys: [...journeys.values()].map(journey => ({
+                    name: journey.name,
+                    team: journey.team,
+                    group: journey.group,
+                    service: journey.service,
+                    verdict: journey.verdict,
+                    reason: journey.reason,
+                    tags: { ...journey.tags },
+                    stepsInFlight: getInFlightSteps(journey).map(step => step.name),
+                    steps: journey.steps.map(step => ({
+                        name: step.name,
+                        outcome: step.outcome,
+                        durationMs: step.durationMs,
+                        ...(step.reason ? { reason: step.reason } : {}),
+                        ...(step.attributedRequestKeys?.length
+                            ? { attributedRequestKeys: [...step.attributedRequestKeys] }
+                            : {}),
+                    })),
+                })),
+                activeStep: active ? { journey: active.journey.name, name: active.name } : null,
+                policyOverlay: {
+                    slowRequests: overlay.slowRequests != null,
+                    httpAbortedRequests: overlay.httpAbortedRequests != null,
+                    httpClientErrorRequests: overlay.httpClientErrorRequests != null,
+                    autoAttributeRequests: overlay.autoAttributeRequests != null,
+                },
+            };
+        },
+
+        firstOpenJourneyName(names) {
             for (const name of names) {
                 if (journeys.has(name)) {
                     return name;
@@ -290,39 +561,51 @@ export function createJourneyRuntime(options: JourneyRuntimeOptions = {}): Journ
         setJourneyTags(name, tags) {
             const journey = name ? journeys.get(name) : undefined;
             if (journey) {
-                Object.assign(journey.tags, tags);
+                assignRecord(journey.tags, tags, MAX_TAG_KEYS);
             }
         },
 
-        startJourney(def) {
-            const existing = journeys.get(def.name);
+        startJourney(config) {
+            const existing = journeys.get(config.name);
             if (existing) {
                 finish(existing, existing.verdict === 'bad' ? 'bad' : 'excluded');
             }
 
+            const tags = emptyRecord();
+            assignRecord(tags, config.tags, MAX_TAG_KEYS);
+            const snapshot = freezeJourneyDef(config, tags);
+            const timeout = resolveJourneyTimeoutMs(snapshot.timeoutMs, defaultJourneyIdleMs);
             const journey: JourneyState = {
-                name: def.name,
-                team: def.team,
-                group: def.group,
-                service: def.service,
+                config: snapshot,
+                name: snapshot.name,
+                team: snapshot.team,
+                group: snapshot.group,
+                service: snapshot.service,
                 verdict: 'good',
                 startedAt: globalThis.performance.now(),
-                timeoutMs: def.timeoutMs ?? 0,
-                stepTimeoutMs: def.stepTimeoutMs,
+                timeoutMs: timeout.ms,
+                timeoutExplicit: timeout.explicit,
+                stepTimeoutMs:
+                    snapshot.stepTimeoutMs !== undefined
+                        ? finiteTimeoutMs(snapshot.stepTimeoutMs)
+                        : undefined,
                 reason: null,
                 steps: [],
-                expected: def.steps ? [...def.steps] : null,
-                tags: { ...(def.tags ?? {}) },
-                requestTimeoutMs: def.requestTimeoutMs,
-                endpoints: sortEndpointsByLongestMatch(def.endpoints),
+                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,
             };
-            journeys.set(def.name, journey);
+            journeys.set(config.name, journey);
+            journey[JOURNEY_ENGINE] = bindJourneyEngine(api, journey, shouldIgnoreRequest);
             armCountdown(journey);
         },
 
-        failJourneyNow(journey, reason) {
+        failJourney(journey, reason) {
             if (journey.closed) {
                 return;
             }
@@ -331,34 +614,81 @@ export function createJourneyRuntime(options: JourneyRuntimeOptions = {}): Journ
             finish(journey, 'bad');
         },
 
-        failJourney(name, reason) {
+        completeJourney(name, tags) {
+            if (!name) {
+                return;
+            }
             const journey = journeys.get(name);
             if (journey) {
-                api.failJourneyNow(journey, reason);
+                api.completeJourneyState(journey, tags);
             }
         },
 
-        completeJourney(name, tags) {
-            if (!name) {
+        completeJourneyState(journey, tags) {
+            if (journey.closed) {
                 return;
             }
             if (tags) {
-                api.setJourneyTags(name, tags);
+                assignRecord(journey.tags, tags, MAX_TAG_KEYS);
             }
-            const journey = journeys.get(name);
-            if (journey) {
-                finish(journey, journey.verdict === 'bad' ? 'bad' : 'good');
+            finish(journey, journey.verdict === 'bad' ? 'bad' : 'good');
+        },
+
+        excludeJourney(journey) {
+            if (journey.closed) {
+                return;
             }
+            finish(journey, journey.verdict === 'bad' ? 'bad' : 'excluded');
         },
 
-        excludeJourney(name) {
-            const journey = journeys.get(name);
-            if (journey) {
-                finish(journey, journey.verdict === 'bad' ? 'bad' : 'excluded');
+        updateOpenJourney(config) {
+            const journey = journeys.get(config.name);
+            if (!journey || journey.closed) {
+                return;
+            }
+            journey.team = config.team;
+            journey.group = config.group;
+            journey.service = config.service;
+            const timeout = resolveJourneyTimeoutMs(config.timeoutMs, defaultJourneyIdleMs);
+            journey.timeoutMs = timeout.ms;
+            journey.timeoutExplicit = timeout.explicit;
+            journey.stepTimeoutMs =
+                config.stepTimeoutMs !== undefined
+                    ? finiteTimeoutMs(config.stepTimeoutMs)
+                    : undefined;
+            journey.slowRequestMs = finiteSlowRequestMs(config.slowRequestMs);
+            journey.endpoints = sortEndpointsByLongestMatch(config.endpoints);
+            journey.expected = config.expected ? [...config.expected] : null;
+            journey.maxSteps =
+                config.maxSteps !== undefined ? clampMaxSteps(config.maxSteps) : undefined;
+            if (config.tags) {
+                assignRecord(journey.tags, config.tags, MAX_TAG_KEYS);
             }
+            clearCountdown(journey);
+            if (journey.timeoutMs <= 0) {
+                return;
+            }
+            const elapsedMs = globalThis.performance.now() - journey.startedAt;
+            const remainingMs = journey.timeoutMs - elapsedMs;
+            if (remainingMs <= 0) {
+                if (journey.timeoutExplicit) {
+                    finish(journey, 'bad', 'journey-timeout');
+                    return;
+                }
+                finish(
+                    journey,
+                    journey.verdict === 'bad' ? 'bad' : 'excluded',
+                    'journey-idle-timeout'
+                );
+                return;
+            }
+            armCountdown(journey, remainingMs);
         },
 
         activeJourneyStep() {
+            if (!api.getAutoAttributeRequests()) {
+                return null;
+            }
             if (inFlight.size !== 1) {
                 return null;
             }
@@ -366,9 +696,14 @@ export function createJourneyRuntime(options: JourneyRuntimeOptions = {}): Journ
         },
 
         async journeyStep(journey, stepName, fn, opts) {
+            maybeAutoStart(journey);
             const journeyName = resolveJourneyName(journey);
             const open = journeyName ? journeys.get(journeyName) : undefined;
             if (!open || !journeyName) {
+                if (isJourneyDebugEnabled()) {
+                    // eslint-disable-next-line no-console -- debug-only untraced hint
+                    console.debug(`[journey] step "${stepName}" ran untraced (no open journey)`);
+                }
                 return fn(noopStep);
             }
 
@@ -377,10 +712,15 @@ export function createJourneyRuntime(options: JourneyRuntimeOptions = {}): Journ
                 startedAt: globalThis.performance.now(),
                 durationMs: 0,
                 outcome: 'good',
-                attributes: {},
+                attributes: emptyRecord(),
                 journey: open,
             };
-            open.steps.push(step);
+            const cap = open.maxSteps ?? maxSteps;
+            if (open.steps.length >= cap) {
+                open.tags.steps_truncated = true;
+            } else {
+                open.steps.push(step);
+            }
 
             const handle = createStepHandle(journeyName, step);
 
@@ -395,7 +735,7 @@ export function createJourneyRuntime(options: JourneyRuntimeOptions = {}): Journ
                     step.reason ??= 'step-timeout';
                     step.attributes.timeout_ms ??= stepTimeoutMs;
                     step.durationMs = Math.round(globalThis.performance.now() - step.startedAt);
-                    api.failJourneyNow(open, 'step-timeout');
+                    api.failJourney(open, 'step-timeout');
                 }, stepTimeoutMs);
             }
 
@@ -403,11 +743,16 @@ export function createJourneyRuntime(options: JourneyRuntimeOptions = {}): Journ
             try {
                 return await fn(handle);
             } catch (err) {
-                const message = err instanceof Error ? err.message : String(err);
-                step.outcome = 'bad';
-                step.reason ??= 'step-error';
-                step.attributes.error ??= message;
-                api.failJourneyNow(open, 'step-error');
+                if (isCanceledError(err)) {
+                    /*
+                     * Attributed abort is scored in onHttpComplete. Unattributed /
+                     * ignored abort throws must not apply policy (empty requestKey).
+                     */
+                } else {
+                    step.outcome = 'bad';
+                    step.reason ??= 'step-error';
+                    api.failJourney(open, 'step-error');
+                }
                 throw err;
             } finally {
                 if (timeoutTimer != null) {
@@ -425,20 +770,29 @@ export function createJourneyRuntime(options: JourneyRuntimeOptions = {}): Journ
             return api.journeyStep(journey, stepName, fn, opts);
         },
 
+        shouldIgnoreRequest,
+
         reportBackendRequest(step, status, durationMs, requestKey) {
-            if (!step) {
+            if (!step?.journey) {
                 return;
             }
             const journey = step.journey;
             if (journey.closed) {
                 return;
             }
-            if (shouldIgnoreRequest(journey, requestKey)) {
+            trackAttributedKey(step, requestKey);
+            const endpointPolicy = resolveEndpointPolicy(
+                journey,
+                effectiveSlowRequests(),
+                requestKey
+            );
+            if (endpointPolicy.ignore) {
                 return;
             }
 
             const failed = status === undefined || status >= 500;
-            const slow = durationMs > resolveRequestTimeoutMs(journey, requestKey);
+            const threshold = endpointPolicy.slowRequestMs;
+            const slow = threshold > 0 && durationMs > threshold;
             if (!failed && !slow) {
                 return;
             }
@@ -451,7 +805,7 @@ export function createJourneyRuntime(options: JourneyRuntimeOptions = {}): Journ
                 step.httpStatus = status;
             }
 
-            api.failJourneyNow(journey, category);
+            api.failJourney(journey, category);
         },
 
         reset(next = {}) {
@@ -461,13 +815,20 @@ export function createJourneyRuntime(options: JourneyRuntimeOptions = {}): Journ
             }
             journeys.clear();
             inFlight.clear();
+            overlay = {};
+            sinksConfigured = false;
             sinks = [...(next.sinks ?? [])];
-            requestTimeouts = {
-                defaultMs: next.requestTimeouts?.defaultMs ?? DEFAULT_REQUEST_TIMEOUTS.defaultMs,
+            slowRequests = {
+                defaultMs: next.slowRequests?.defaultMs ?? DEFAULT_SLOW_REQUESTS.defaultMs,
                 endpoints: sortEndpointsByLongestMatch(
-                    next.requestTimeouts?.endpoints ?? DEFAULT_REQUEST_TIMEOUTS.endpoints
+                    next.slowRequests?.endpoints ?? DEFAULT_SLOW_REQUESTS.endpoints
                 ),
             };
+            maxSteps =
+                next.maxSteps !== undefined ? clampMaxSteps(next.maxSteps) : DEFAULT_MAX_STEPS;
+            defaultJourneyIdleMs = finiteTimeoutMs(
+                next.defaultJourneyIdleMs ?? DEFAULT_JOURNEY_IDLE_MS
+            );
         },
     };
 
@@ -476,14 +837,76 @@ export function createJourneyRuntime(options: JourneyRuntimeOptions = {}): Journ
 
 /**
  * @internal Private — not part of the public package API.
- * Process-wide engine used by free helpers. App code does not need to touch this.
+ * Module-scoped engine used by free helpers. App code does not need to touch this.
+ * Each host/MFE bundle gets its own copy when the package is duplicated.
  */
-export const defaultRuntime: JourneyRuntime = createJourneyRuntime();
+export const moduleRuntime: JourneyRuntime = createJourneyRuntime();
+
+const noopEngine: JourneyEngine = {
+    failJourney() {},
+    exclude() {},
+    shouldIgnoreRequest() {
+        return false;
+    },
+    reportBackendRequest() {},
+    getHttpAbortedRequestsPolicy() {
+        return 'continue';
+    },
+    getHttpClientErrorRequestsPolicy() {
+        return 'continue';
+    },
+};
+
+/**
+ * True when this bundle can fail/exclude/report the journey: stamped engine, or
+ * this runtime's own unstamped object. False for a foreign older-copy journey.
+ */
+export function canRouteHttpToJourney(journey: JourneyState): boolean {
+    return (
+        journey[JOURNEY_ENGINE] != null || moduleRuntime.getOpenJourney(journey.name) === journey
+    );
+}
+
+/**
+ * @internal Prefer the creating engine on a journey (MFE `step.stamp()` on a host transport).
+ * Falls back to this bundle's module runtime only when this runtime owns the object.
+ * Unstamped foreign journeys (older package copies) are a no-op so a same-named
+ * host journey is not deleted from this map.
+ */
+export function resolveJourneyEngine(journey: JourneyState): JourneyEngine {
+    const stamped = journey[JOURNEY_ENGINE];
+    if (stamped) {
+        return stamped;
+    }
+    if (moduleRuntime.getOpenJourney(journey.name) !== journey) {
+        return noopEngine;
+    }
+    return {
+        failJourney(reason) {
+            moduleRuntime.failJourney(journey, reason);
+        },
+        exclude() {
+            moduleRuntime.excludeJourney(journey);
+        },
+        shouldIgnoreRequest(key) {
+            return moduleRuntime.shouldIgnoreRequest(journey, key);
+        },
+        reportBackendRequest(step, status, durationMs, requestKey) {
+            moduleRuntime.reportBackendRequest(step, status, durationMs, requestKey);
+        },
+        getHttpAbortedRequestsPolicy() {
+            return moduleRuntime.getHttpAbortedRequestsPolicy();
+        },
+        getHttpClientErrorRequestsPolicy() {
+            return moduleRuntime.getHttpClientErrorRequestsPolicy();
+        },
+    };
+}
 
 /**
- * Reset the default engine (open journeys, ambient steps, sinks, request thresholds).
+ * @internal Reset the module engine (open journeys, ambient steps, sinks, slow-request thresholds).
  * Intended for tests — call in `beforeEach` / `afterEach` instead of manual cleanup.
  */
 export function resetJourney(options?: JourneyRuntimeOptions): void {
-    defaultRuntime.reset(options);
+    moduleRuntime.reset(options);
 }