@servicetitan/journey 2.0.0 → 3.0.0

package/src/config.ts

@@ -1,10 +1,15 @@
-import { defaultRuntime } from './core/runtime';
-import { setJourneySinks, type JourneySink } from './core/registry';
+import { moduleRuntime } from './core/runtime';
+import type { JourneySink } from './core/types';
+import type { RequestPolicyConfig } from './core/request-policy';
 import {
-    sortEndpointsByLongestMatch,
-    type AppRequestTimeouts,
-    type EndpointPolicy,
-} from './endpoint-policy';
+    areSharedPoliciesLocked,
+    getSharedSlowRequests,
+    isJourneyEnabled,
+    registerJourneyRuntime,
+    seedSharedPolicies,
+    warnIfSlowRequestsUnset,
+} from './global';
+import { sortEndpointsByLongestMatch, type SlowRequestConfig } from './core/endpoint-policy';
 import { instrumentAxios, type AxiosLikeInstance } from './integrations/axios';
 import { instrumentFetch, type InstrumentFetchOptions } from './integrations/fetch';
 import {
@@ -13,33 +18,73 @@ import {
     type JqueryStatic,
     type WindowWithAppJourney,
 } from './integrations/jquery';
+import { resolveGlobalJquery } from './integrations/jquery/instrument';
+import { sendToConsole } from './sinks/console';
 import { sendToDatadog } from './sinks/datadog';
 
-export { longestEndpointMatch, sortEndpointsByLongestMatch } from './endpoint-policy';
-export type { AppRequestTimeouts, EndpointPolicy };
-
 /** Optional app-wide / per-bundle configuration. */
 export interface JourneyConfig {
-    /** App-wide request-timeout fallback. Defaults to { defaultMs: 4000, endpoints: [] }. */
-    requestTimeouts?: AppRequestTimeouts;
+    /**
+     * App-wide slow-request thresholds (shared on `__stJourney` for all package copies).
+     * Package fallback remains `{ defaultMs: 4000, endpoints: [] }` until set.
+     * Desktop / KO hosts should set `defaultMs` and ignore noisy endpoint prefixes.
+     */
+    slowRequests?: SlowRequestConfig;
+    /**
+     * How attributed aborted/cancelled HTTP counts toward the open journey.
+     * Shared on `__stJourney`. Literal or `(ctx) => …`. Default `'continue'`.
+     */
+    httpAbortedRequests?: RequestPolicyConfig;
+    /**
+     * How attributed 4xx responses count toward the open journey.
+     * Shared on `__stJourney`. Literal or `(ctx) => …`. Default `'continue'` (no verdict change).
+     */
+    httpClientErrorRequests?: RequestPolicyConfig;
+    /**
+     * When true (default), untagged instrumented HTTP is attributed to the sole
+     * in-flight step (if exactly one). When false, only explicit `step.stamp()` attributes.
+     * Prefer false on busy desktop / shared jQuery shells with background traffic.
+     * Shared on `__stJourney`.
+     */
+    autoAttributeRequests?: boolean;
+    /**
+     * Default cap on recorded steps per journey (default 50). Per-journey
+     * `JourneyDef.maxSteps` overrides. Excess steps are dropped and
+     * `tags.steps_truncated` is set.
+     */
+    maxSteps?: number;
+    /**
+     * Applied when a journey omits `timeoutMs`.
+     * Default is 15m and closes as `excluded` with `journey-idle-timeout`.
+     * Pass `0` to disable this idle timeout.
+     */
+    defaultJourneyIdleMs?: number;
     /**
      * Replace the sink list used when a journey finishes.
      * Only applied when provided — omit to leave the current list unchanged.
-     * Package default is `[sendToDatadog]`; pass `[]` to disable emission.
+     * Package default is `[sendToDatadog, sendToConsole]`; pass `[]` to disable emission.
+     * `sendToConsole` is a no-op unless `sessionStorage['st:journey:debug'] === 'true'`.
+     * First `sinks` on this bundle wins; a later `configureJourney({ sinks })` is ignored.
      */
     sinks?: readonly JourneySink[];
     /**
      * Wire this bundle's axios instance (host or MFE). Same as `instrumentAxios(axios)`.
      * Register any async request interceptors (e.g. auth) before `configureJourney`.
+     * Soft-skips when axios is missing / not axios-like — safe to pass a host instance that may be absent.
      */
-    axios?: AxiosLikeInstance;
+    axios?: AxiosLikeInstance | null;
     /**
      * Wire fetch. `true` wraps `globalThis.fetch`; pass options for a scoped target / baseURL.
-     * Same as `instrumentFetch(...)`.
+     * Same as `instrumentFetch(...)`. Soft-skips when the target has no callable `fetch`.
+     * Prefer host-only for `globalThis.fetch` — MFEs inherit the host wrapper.
      */
-    fetch?: true | InstrumentFetchOptions;
-    /** Wire this bundle's jQuery static. Same as `instrumentJquery($)`. */
-    jquery?: JqueryStatic;
+    fetch?: true | InstrumentFetchOptions | null;
+    /**
+     * Wire jQuery. Pass a `$` instance, or `true` to use `globalThis.$` / `globalThis.jQuery`.
+     * `false` skips wiring. Soft-skips when `$` is missing / not real jQuery.
+     * Prefer host-only for shared `$`.
+     */
+    jquery?: boolean | JqueryStatic | null;
     /**
      * Publish `window.App.Journey` for Knockout / legacy hosts.
      * `true` uses the real window; pass a target object in tests.
@@ -48,40 +93,127 @@ export interface JourneyConfig {
 }
 
 /*
- * Default emission target. Kept as a module side effect so any import of this file
- * (see index.ts `import './config'`) installs Datadog. configureJourney only replaces
- * sinks when `sinks` is passed explicitly.
+ * Default emission targets + `__stJourney` bag. Kept as a module side effect so any import
+ * of this file (see index.ts `import './config'`) installs Datadog, console, and
+ * `__stJourney`. configureJourney only replaces sinks when `sinks` is passed explicitly.
  */
-setJourneySinks([sendToDatadog]);
+moduleRuntime.setSinks([sendToDatadog, sendToConsole]);
+registerJourneyRuntime(moduleRuntime);
 
 /**
  * Apply bundle options: request thresholds, sinks, and/or HTTP / legacy wiring.
  * Optional — call once at startup. Pass this bundle's own axios / `$` / fetch target.
+ * Policy knobs (`slowRequests`, `httpAbortedRequests`, `httpClientErrorRequests`,
+ * `autoAttributeRequests`) are stored on shared `__stJourney` so MFEs inherit host settings.
+ * No-ops when `isJourneyEnabled()` is false (host default or force flag).
+ * Never throws: missing/invalid config and failures soft-skip (warn / error to console).
  */
 export function configureJourney(config: JourneyConfig): void {
-    if (config.requestTimeouts !== undefined) {
-        defaultRuntime.setRequestTimeouts({
-            ...config.requestTimeouts,
-            endpoints: sortEndpointsByLongestMatch(config.requestTimeouts.endpoints),
-        });
-    }
-    if (config.sinks !== undefined) {
-        setJourneySinks(config.sinks);
-    }
-    if (config.axios !== undefined) {
-        instrumentAxios(config.axios);
+    if (config == null || typeof config !== 'object') {
+        // eslint-disable-next-line no-console -- soft-skip missing host config
+        console.warn('[journey] configureJourney: skipped — missing');
+        return;
     }
-    if (config.fetch !== undefined) {
-        instrumentFetch(config.fetch === true ? {} : config.fetch);
+    if (!isJourneyEnabled()) {
+        // eslint-disable-next-line no-console -- soft-skip when host default and force are off
+        console.warn(
+            '[journey] configureJourney: skipped — disabled (call setJourneyDefaultEnabled(true) or __stJourney.enable(), then configureJourney again / reload)'
+        );
+        return;
     }
-    if (config.jquery !== undefined) {
-        instrumentJquery(config.jquery);
-    }
-    if (config.exposeAppJourney) {
-        exposeAppJourney(config.exposeAppJourney === true ? undefined : config.exposeAppJourney);
+
+    try {
+        const overlay: {
+            slowRequests?: SlowRequestConfig;
+            httpAbortedRequests?: RequestPolicyConfig;
+            httpClientErrorRequests?: RequestPolicyConfig;
+            autoAttributeRequests?: boolean;
+        } = {};
+
+        const policyPatch: Parameters<typeof seedSharedPolicies>[0] = {};
+        let hasPolicyKnob = false;
+
+        if (config.slowRequests !== undefined) {
+            const sorted = {
+                ...config.slowRequests,
+                endpoints: sortEndpointsByLongestMatch(config.slowRequests.endpoints),
+            };
+            policyPatch.slowRequests = sorted;
+            policyPatch.slowRequestsConfigured = true;
+            overlay.slowRequests = sorted;
+            hasPolicyKnob = true;
+        }
+        if (config.httpAbortedRequests !== undefined) {
+            policyPatch.httpAbortedRequests = config.httpAbortedRequests;
+            overlay.httpAbortedRequests = config.httpAbortedRequests;
+            hasPolicyKnob = true;
+        }
+        if (config.httpClientErrorRequests !== undefined) {
+            policyPatch.httpClientErrorRequests = config.httpClientErrorRequests;
+            overlay.httpClientErrorRequests = config.httpClientErrorRequests;
+            hasPolicyKnob = true;
+        }
+        if (config.autoAttributeRequests !== undefined) {
+            policyPatch.autoAttributeRequests = config.autoAttributeRequests;
+            overlay.autoAttributeRequests = config.autoAttributeRequests;
+            hasPolicyKnob = true;
+        }
+
+        if (hasPolicyKnob) {
+            if (!areSharedPoliciesLocked()) {
+                seedSharedPolicies(policyPatch);
+            }
+            moduleRuntime.setPolicyOverlay(overlay);
+        }
+        if (config.maxSteps !== undefined) {
+            moduleRuntime.setMaxSteps(config.maxSteps);
+        }
+        if (config.defaultJourneyIdleMs !== undefined) {
+            moduleRuntime.setDefaultJourneyIdleMs(config.defaultJourneyIdleMs);
+        }
+        if (config.sinks !== undefined) {
+            if (!moduleRuntime.trySetConfiguredSinks(config.sinks)) {
+                // eslint-disable-next-line no-console -- first-writer sinks
+                console.warn(
+                    '[journey] configureJourney: sinks already set on this runtime — ignoring'
+                );
+            }
+        }
+
+        const wiringTransport =
+            config.axios !== undefined ||
+            config.fetch !== undefined ||
+            (config.jquery !== undefined && config.jquery !== false);
+        if (wiringTransport) {
+            warnIfSlowRequestsUnset();
+        }
+
+        if (config.axios !== undefined) {
+            instrumentAxios(config.axios);
+        }
+        if (config.fetch !== undefined) {
+            instrumentFetch(config.fetch === true ? {} : config.fetch);
+        }
+        if (config.jquery === true) {
+            instrumentJquery(resolveGlobalJquery());
+        } else if (config.jquery !== undefined && config.jquery !== false) {
+            instrumentJquery(config.jquery);
+        }
+        if (config.exposeAppJourney) {
+            exposeAppJourney(
+                config.exposeAppJourney === true ? undefined : config.exposeAppJourney
+            );
+        }
+    } catch (err) {
+        // eslint-disable-next-line no-console -- soft-fail host wiring
+        console.error('[journey] configureJourney failed', err);
     }
 }
 
-export function getRequestTimeouts(): AppRequestTimeouts {
-    return defaultRuntime.getRequestTimeouts();
+/**
+ * @internal Read the module runtime's app-wide slow-request config.
+ * Prefer `configureJourney({ slowRequests })` to set thresholds. Test / introspection only.
+ */
+export function getSlowRequests(): SlowRequestConfig {
+    return getSharedSlowRequests() ?? moduleRuntime.getSlowRequests();
 }

package/src/core/abort-error.ts

@@ -0,0 +1,24 @@
+export function isAbortError(error: unknown): boolean {
+    if (error == null || typeof error !== 'object') {
+        return false;
+    }
+    const err = error as { name?: string; code?: string | number };
+    if (err.name === 'AbortError' || err.name === 'CanceledError') {
+        return true;
+    }
+    return err.code === 'ERR_CANCELED';
+}
+
+/** Axios cancel token, CanceledError, AbortError, or ERR_CANCELED. */
+export function isCanceledError(error: unknown): boolean {
+    if (isAbortError(error)) {
+        return true;
+    }
+    if (error == null || typeof error !== 'object') {
+        return false;
+    }
+    /* eslint-disable @typescript-eslint/naming-convention -- axios Cancel token wire format */
+    const err = error as { __CANCEL__?: boolean };
+    return err.__CANCEL__ === true;
+    /* eslint-enable @typescript-eslint/naming-convention */
+}

package/src/core/api.ts

@@ -0,0 +1,159 @@
+import { moduleRuntime, resolveJourneyEngine } from './runtime';
+import { adoptJourneyStepStamp, JourneyStepStamp } from './step-tag';
+import type {
+    JourneyDef,
+    JourneyHandle,
+    JourneyStepOptions,
+    JourneyStepTarget,
+    StepHandle,
+    StepRecord,
+    TagValue,
+} from './types';
+
+let ambientStamp: JourneyStepStamp | null = null;
+let ambientStep: StepRecord | null = null;
+
+/**
+ * Unique in-flight step as a stamp-ready {@link JourneyStepStamp}, or null when
+ * auto-attribute is disabled, or when 0 or 2+ steps are in flight app-wide.
+ * Ambient stamps never carry `score` or `ignore`. Untagged traffic is attributed
+ * to that lone step even if unrelated — prefer `step.stamp()` when the page has
+ * background instrumented requests. Disable via
+ * `configureJourney({ autoAttributeRequests: false })`.
+ */
+export function singleInFlightJourneyStep(): JourneyStepStamp | null {
+    if (ambientStep?.journey.closed) {
+        ambientStep = null;
+        ambientStamp = null;
+    }
+    const activeStep = moduleRuntime.activeJourneyStep();
+    if (!activeStep) {
+        ambientStamp = null;
+        ambientStep = null;
+        return null;
+    }
+    if (ambientStep === activeStep && ambientStamp) {
+        return ambientStamp;
+    }
+    ambientStep = activeStep;
+    ambientStamp = new JourneyStepStamp(activeStep);
+    return ambientStamp;
+}
+
+/** @internal Clear cached ambient stamp when runtime state changes. */
+export function invalidateAmbientStamp(step?: StepRecord): void {
+    if (!step || step === ambientStep) {
+        ambientStamp = null;
+        ambientStep = null;
+    }
+}
+
+/**
+ * Prefer an explicit `step.stamp()` value; else the ambient in-flight stamp.
+ * Same-realm stamps are returned as-is (identity + score + ignore). Branded
+ * foreign copies are adopted into a local stamp. Raw StepRecords are not stamps.
+ */
+export function resolveStamp(explicit?: unknown): JourneyStepStamp | undefined {
+    const fromExplicit = adoptJourneyStepStamp(explicit);
+    if (fromExplicit) {
+        return fromExplicit;
+    }
+    return singleInFlightJourneyStep() ?? undefined;
+}
+
+/**
+ * Record a finished backend request against a captured step.
+ * 5xx / network / slow (over threshold) mark Bad; 4xx is not counted. Fail-fast on breach.
+ * @internal Prefer {@link onHttpComplete} from adapters.
+ */
+export function reportBackendRequest(
+    step: StepRecord | undefined,
+    status: number | undefined,
+    durationMs: number,
+    requestKey: string
+): void {
+    if (!step?.journey) {
+        return;
+    }
+    resolveJourneyEngine(step.journey).reportBackendRequest(step, status, durationMs, requestKey);
+}
+
+/**
+ * Run one step of a named journey. Runs untraced (noop handle) when no matching journey is open.
+ * `journey` may be a name, null, an ordered candidate list, a def, or a handle.
+ * A def or handle auto-starts when that journey is not already open; a bare name does not.
+ * Prefer `defineJourney(...).step` when you own the journey config.
+ */
+export async function journeyStep<T>(
+    journey: JourneyStepTarget,
+    stepName: string,
+    fn: (step: StepHandle) => T | Promise<T>,
+    opts?: JourneyStepOptions
+): Promise<T> {
+    return moduleRuntime.journeyStep(journey, stepName, fn, opts);
+}
+
+/** Merge custom tags onto an open journey. No-op if not open. Prefer `handle.setTags`. */
+export function setJourneyTags(name: string | null, tags: Record<string, TagValue>): void {
+    moduleRuntime.setJourneyTags(name, tags);
+}
+
+/** Mark a named journey Bad for a custom reason (fail-fast). Prefer `handle.fail`. */
+export function failJourney(name: string, reason: string): void {
+    const journey = moduleRuntime.getOpenJourney(name);
+    if (journey) {
+        moduleRuntime.failJourney(journey, reason);
+    }
+}
+
+/** Successful end. Outcome stays Bad if a breach already occurred. No-op when name is null. Prefer `handle.complete`. */
+export function completeJourney(name: string | null, tags?: Record<string, TagValue>): void {
+    moduleRuntime.completeJourney(name, tags);
+}
+
+/** User left before finishing. Stays Bad if a breach already occurred (breach-anchored). Prefer `handle.exclude`. */
+export function excludeJourney(name: string): void {
+    const journey = moduleRuntime.getOpenJourney(name);
+    if (journey) {
+        moduleRuntime.excludeJourney(journey);
+    }
+}
+
+/** Turn a journey config into a handle with bound lifecycle methods. Preferred public API. */
+export function defineJourney(config: JourneyDef): JourneyHandle {
+    return {
+        config,
+        start(tags) {
+            moduleRuntime.startJourney(config);
+            if (tags) {
+                moduleRuntime.setJourneyTags(config.name, tags);
+            }
+        },
+        step(stepName, fn, opts) {
+            if (!moduleRuntime.getOpenJourney(config.name)) {
+                moduleRuntime.startJourney(config);
+            }
+            return journeyStep(config.name, stepName, fn, opts);
+        },
+        async mountStep(stepName, fn, opts) {
+            // Defer so a parent <JourneyScope> opens first (child effects run before parent).
+            await Promise.resolve();
+            if (!moduleRuntime.getOpenJourney(config.name)) {
+                moduleRuntime.startJourney(config);
+            }
+            return journeyStep(config.name, stepName, fn, opts);
+        },
+        complete(tags) {
+            completeJourney(config.name, tags);
+        },
+        fail(reason) {
+            failJourney(config.name, reason);
+        },
+        exclude() {
+            excludeJourney(config.name);
+        },
+        setTags(tags) {
+            setJourneyTags(config.name, tags);
+        },
+    };
+}

package/src/{endpoint-policy.ts → core/endpoint-policy.ts}

@@ -1,3 +1,5 @@
+import type { JourneyState } from './types';
+
 /** Per-endpoint request policy (app-wide or per-journey). Longest matching prefix wins. */
 export interface EndpointPolicy {
     /**
@@ -7,20 +9,25 @@ export interface EndpointPolicy {
      * `match` already supplies the boundary.
      */
     match: string;
-    /** Custom slow-request threshold in ms; omit / 0 falls through. */
-    timeoutMs?: number;
-    /** When true, errors and slow responses never mark the journey Bad. */
+    /** Custom slow-request threshold in ms; omit to fall through. `0` disables latency scoring for this prefix. */
+    slowRequestMs?: number;
+    /** When true, this endpoint never changes the journey verdict (errors, latency, aborts, 4xx). */
     ignore?: boolean;
 }
 
 /** App-wide slow-request threshold fallback (not an axios abort). */
-export interface AppRequestTimeouts {
+export interface SlowRequestConfig {
     /** Fallback threshold when no endpoint or journey override applies. */
     defaultMs: number;
     /** App-wide endpoint overrides; journey-specific ones belong on JourneyDef.endpoints. */
     endpoints?: readonly EndpointPolicy[];
 }
 
+export interface ResolvedEndpointPolicy {
+    ignore: boolean;
+    slowRequestMs: number;
+}
+
 /** Copy sorted longest-match-first so lookup can return on the first hit. */
 export function sortEndpointsByLongestMatch(
     endpoints: readonly EndpointPolicy[] | undefined
@@ -64,3 +71,38 @@ export function longestEndpointMatch(
     }
     return undefined;
 }
+
+/**
+ * Resolve ignore + latency threshold with longest-prefix matching.
+ * Journey overrides win over app defaults for slow thresholds.
+ */
+export function resolveEndpointPolicy(
+    journey: JourneyState,
+    appSlow: SlowRequestConfig,
+    requestKey: string
+): ResolvedEndpointPolicy {
+    const own = longestEndpointMatch(journey.endpoints, requestKey);
+    if (own?.ignore === true) {
+        return { ignore: true, slowRequestMs: 0 };
+    }
+
+    const app = longestEndpointMatch(appSlow.endpoints, requestKey);
+    if (own) {
+        return {
+            ignore: false,
+            slowRequestMs:
+                own.slowRequestMs ??
+                app?.slowRequestMs ??
+                journey.slowRequestMs ??
+                appSlow.defaultMs,
+        };
+    }
+    if (app?.ignore === true) {
+        return { ignore: true, slowRequestMs: 0 };
+    }
+
+    return {
+        ignore: false,
+        slowRequestMs: app?.slowRequestMs ?? journey.slowRequestMs ?? appSlow.defaultMs,
+    };
+}

package/src/core/index.ts

@@ -1,39 +1,38 @@
-/** Core engine barrel — free helpers over the default runtime, plus handles and types. */
+/** Core barrel — public free helpers, handles, and types. Engine lives in `./runtime`. */
 
 export {
-    activeJourneyStep,
-    addJourneySink,
     completeJourney,
     defineJourney,
-    emitJourneyEvent,
     excludeJourney,
     failJourney,
-    firstOpenJourney,
-    journeyMountStep,
     journeyStep,
     reportBackendRequest,
-    setJourneySinks,
+    resolveStamp,
     setJourneyTags,
-    startJourney,
-    type JourneyHandle,
-    type JourneySink,
-} from './registry';
+    singleInFlightJourneyStep,
+} from './api';
 export {
-    createJourneyRuntime,
-    defaultRuntime,
+    // @internal Test helper — not a supported consumer API.
     resetJourney,
-    type JourneyRuntime,
-    type JourneyRuntimeOptions,
 } from './runtime';
 export type {
     JourneyDef,
     JourneyEvent,
+    JourneyHandle,
     JourneyNameLike,
+    JourneySink,
     JourneyStepEvent,
     JourneyStepOptions,
-    JourneyStepRef,
     JourneyStepTarget,
     StepHandle,
     TagValue,
 } from './types';
-export { JourneyStepTag, resolveJourneyStep } from './step-tag';
+export { JourneyStepStamp } from './step-tag';
+export type {
+    JourneyHttpPolicyContext,
+    JourneyHttpScore,
+    JourneyHttpScoreContext,
+    JourneyRequestPolicy,
+    JourneyStampOptions,
+    RequestPolicyConfig,
+} from './request-policy';

package/src/core/limits.ts

@@ -0,0 +1,73 @@
+/** Payload / timer bounds shared by the engine and default sinks. */
+
+export const DEFAULT_MAX_STEPS = 50;
+export const MAX_STEPS_CAP = 200;
+export const MAX_TAG_KEYS = 32;
+export const MAX_ATTRIBUTE_KEYS = 64;
+export const MAX_ATTRIBUTED_REQUEST_KEYS = 50;
+export const MAX_TAG_VALUE_LEN = 200;
+export const DEFAULT_JOURNEY_IDLE_MS = 15 * 60 * 1_000;
+
+const DENIED_KEYS = new Set([
+    '__proto__',
+    'constructor',
+    'prototype',
+    'authorization',
+    'cookie',
+    'set-cookie',
+    'password',
+    'token',
+    'secret',
+    'ssn',
+]);
+
+/** True for prototype-polluting keys and a small secret-name deny-list (case-insensitive). */
+export function isUnsafeKey(key: string): boolean {
+    return DENIED_KEYS.has(key.toLowerCase());
+}
+
+/**
+ * Finite integer ≥ 1, else `fallback`. Used for maxSteps-like caps.
+ * Non-finite / ≤ 0 / non-numbers return `fallback`.
+ */
+export function finitePositiveInt(n: unknown, fallback: number): number {
+    if (typeof n !== 'number' || !Number.isFinite(n) || n <= 0) {
+        return fallback;
+    }
+    return Math.floor(n);
+}
+
+/**
+ * Journey/step timeout: finite ≥ 0 keeps the value (floored); anything else is 0 (disabled).
+ */
+export function finiteTimeoutMs(n: unknown): number {
+    if (typeof n !== 'number' || !Number.isFinite(n) || n < 0) {
+        return 0;
+    }
+    return Math.floor(n);
+}
+
+/** Clamp recorded-step cap to 1..MAX_STEPS_CAP; invalid → DEFAULT_MAX_STEPS. */
+export function clampMaxSteps(n: unknown): number {
+    const value = finitePositiveInt(n, DEFAULT_MAX_STEPS);
+    return Math.min(value, MAX_STEPS_CAP);
+}
+
+/** Finite ≥ 0 slow-request threshold, or undefined to fall through. */
+export function finiteSlowRequestMs(n: unknown): number | undefined {
+    if (typeof n !== 'number' || !Number.isFinite(n) || n < 0) {
+        return undefined;
+    }
+    return Math.floor(n);
+}
+
+/** Explicit 0 disables; omitted uses idle default; finite N keeps caller timeout. */
+export function resolveJourneyTimeoutMs(
+    timeoutMs: number | undefined,
+    idleDefaultMs: number = DEFAULT_JOURNEY_IDLE_MS
+): { ms: number; explicit: boolean } {
+    if (timeoutMs === undefined) {
+        return { ms: finiteTimeoutMs(idleDefaultMs), explicit: false };
+    }
+    return { ms: finiteTimeoutMs(timeoutMs), explicit: true };
+}