crumbtrail-core 0.1.0

package/dist/index.d.ts

@@ -0,0 +1,960 @@
+interface PersistedSession {
+    id: string;
+    lastActivity: number;
+}
+interface SessionStore {
+    read(): PersistedSession | undefined;
+    write(session: PersistedSession): void;
+}
+declare const DEFAULT_SESSION_STORAGE_KEY = "__crumbtrail_session";
+declare function createWebSessionStore(storage?: Pick<Storage, "getItem" | "setItem">, key?: string): SessionStore | undefined;
+
+declare const CRUMBTRAIL_SCHEMA_VERSION: 1;
+declare const CRUMBTRAIL_EVENT_KINDS: {
+    readonly navigation: "navigation";
+    readonly appLifecycle: "app-lifecycle";
+    readonly nativeCrash: "native-crash";
+    readonly viewSnapshot: "view-snapshot";
+};
+type CrumbtrailPlatform = "web" | "react-native" | "ios" | "android" | "flutter" | "webview" | "node";
+interface CrumbtrailSdkDescriptor {
+    name: string;
+    version?: string;
+}
+type CrumbtrailCapabilities = string[];
+type RequireAtLeastOne<T, Keys extends keyof T = keyof T> = Pick<T, Exclude<keyof T, Keys>> & {
+    [K in Keys]-?: Required<Pick<T, K>> & Partial<Pick<T, Exclude<Keys, K>>>;
+}[Keys];
+type TargetDescriptorIdentityKey = "role" | "label" | "testID" | "accessibilityId" | "componentName" | "routePath" | "ancestryHash";
+interface TargetDescriptorBase {
+    /** Semantic role of the target, e.g. button, link, textbox, screen, view. */
+    role?: string;
+    /** Human-readable label visible to or announced for the user. */
+    label?: string;
+    /** Stable test identifier supplied by the app. */
+    testID?: string;
+    /** Stable accessibility/native identifier supplied by the app. */
+    accessibilityId?: string;
+    /** Framework component or native view name. */
+    componentName?: string;
+    /** App route or screen path where the target appears. */
+    routePath?: string;
+    /** Privacy-safe hash of the target's ancestor path. */
+    ancestryHash?: string;
+    bounds?: {
+        x: number;
+        y: number;
+        width: number;
+        height: number;
+    };
+    redaction?: unknown;
+    /** @deprecated Use testID. Accepted while legacy web/mobile emitters migrate. */
+    testId?: string;
+    /** @deprecated Use accessibilityId or label. Accepted while legacy emitters migrate. */
+    accessibilityLabel?: string;
+    /** @deprecated Use label. Accepted while legacy web emitters migrate. */
+    text?: string;
+    /** @deprecated Use componentName. Accepted while legacy emitters migrate. */
+    viewName?: string;
+    /** @deprecated Use routePath. Accepted while legacy emitters migrate. */
+    screen?: string;
+    /** @deprecated Accepted while legacy web emitters migrate. */
+    selector?: string;
+}
+type TargetDescriptor = RequireAtLeastOne<TargetDescriptorBase, TargetDescriptorIdentityKey>;
+interface BugEvent {
+    /** Unix timestamp in milliseconds */
+    t: number;
+    /** Event category short code */
+    k: string;
+    /** Type-specific payload */
+    d: Record<string, unknown>;
+    /** Version of the shared event envelope. Missing means v1 for backward compatibility. */
+    schemaVersion?: typeof CRUMBTRAIL_SCHEMA_VERSION;
+    /** Source runtime. Missing means `web` for backward compatibility with current browser SDKs. */
+    platform?: CrumbtrailPlatform;
+    /** SDK identity for non-browser and future SDKs. */
+    sdk?: CrumbtrailSdkDescriptor;
+    /** Optional capability names enabled by the emitting SDK/session. */
+    capabilities?: CrumbtrailCapabilities;
+    /** Optional normalized target reference for web/mobile events. */
+    target?: TargetDescriptor;
+    /** Active recording session identifier when an extension workflow session owns the event. */
+    sessionId?: string;
+    /** Milliseconds elapsed from the active recording session's canonical startedAt timestamp. */
+    offsetMs?: number;
+}
+interface BugReport {
+    bugId: string;
+    sessionId: string;
+    flaggedAt: number;
+    windowMs: number;
+    note?: string;
+    voiceNote?: string;
+    url: string;
+    userAgent: string;
+    tags?: string[];
+    summary: {
+        errorCount: number;
+        failedRequestCount: number;
+        eventCount: number;
+        eventKinds: Record<string, number>;
+        durationMs: number;
+        stateProviderCount?: number;
+    };
+}
+/** Canonical event kind for a database row diff (`k:'db.diff'`). */
+declare const DB_DIFF_EVENT_KIND: "db.diff";
+/**
+ * Canonical event kind for an aggregate capped database diff summary (`k:'db.diff.bulk'`).
+ * The comparator intentionally ignores this kind: over-cap statements are treated as batch work,
+ * while per-row `db.diff` events remain the UI-flow comparison signal.
+ */
+declare const DB_DIFF_BULK_EVENT_KIND: "db.diff.bulk";
+/** Canonical event kind for a capped database read row (`k:'db.read'`). */
+declare const DB_READ_EVENT_KIND: "db.read";
+/** Canonical event kind for an aggregate capped database read summary (`k:'db.read.bulk'`). */
+declare const DB_READ_BULK_EVENT_KIND: "db.read.bulk";
+/** Mutating operation a `db.diff` event records. */
+type DbDiffOp = "insert" | "update" | "delete";
+/**
+ * Database engine that produced a `db.diff` / `db.read` event. Downstream consumers (evidence
+ * index, fix-context, comparator) treat every engine identically — the engine tag exists so
+ * agents and humans know which dialect the captured statement ran against.
+ */
+type DbEngine = "postgres" | "mysql" | "mssql" | "sqlite";
+/**
+ * Type-specific payload (`d`) of a `k:'db.diff'` event: the row(s) that changed for one
+ * mutating statement, correlated to the request that caused them via `requestId` (which equals
+ * the active request's traceId per the correlation bridge in `correlation.ts`). `after` carries
+ * the post-image (insert/update); `before` is the pre-image, only present when before-capture is
+ * enabled (and for deletes it carries the removed row). Sensitive columns are redacted out of
+ * `after`/`before`/`pk` before the event ever rests. The shape is identical across engines; only
+ * the `engine` tag differs.
+ */
+interface DbDiffEventData {
+    engine: DbEngine;
+    op: DbDiffOp;
+    table: string;
+    /** Primary-key column→value map identifying the affected row, or `null` when unresolved. */
+    pk: Record<string, unknown> | null;
+    /** Post-image of the affected row (insert/update); omitted for deletes. */
+    after?: Record<string, unknown>;
+    /** Pre-image of the affected row; only captured behind the before-capture flag (and for deletes). */
+    before?: Record<string, unknown>;
+    /**
+     * Present only on an image-less statement-level fallback event where per-row images were
+     * unobtainable (e.g. a MySQL multi-row insert). Such events carry `pk: null` and no
+     * `after`/`before`; this records how many rows the statement changed so the write stays visible.
+     */
+    rowCount?: number;
+    /** Correlation id; equals the active request's traceId so it lands in the same evidence window. */
+    requestId: string;
+    /** Redaction metadata for any column-level values dropped/masked before rest. */
+    redaction?: unknown;
+}
+/**
+ * Type-specific payload (`d`) of a `k:'db.diff.bulk'` event emitted when a mutating statement
+ * affects more rows than the configured per-statement `db.diff` cap. It summarizes truncation
+ * without duplicating every changed row payload.
+ */
+interface DbDiffBulkEventData {
+    engine: DbEngine;
+    op: DbDiffOp;
+    table: string;
+    requestId: string;
+    rowCount: number;
+    emittedRows: number;
+    truncatedRows: number;
+    samplePks: Array<Record<string, unknown>>;
+}
+/**
+ * Type-specific payload (`d`) of a `k:'db.read'` event: one redacted row read by a SELECT within
+ * an active request scope. Disabled by default because read capture can increase PII surface.
+ */
+interface DbReadEventData {
+    engine: DbEngine;
+    table: string;
+    pk: Record<string, unknown> | null;
+    row: Record<string, unknown>;
+    requestId: string;
+    redaction?: unknown;
+}
+/**
+ * Type-specific payload (`d`) of a `k:'db.read.bulk'` event emitted when a SELECT returns more rows
+ * than the configured read cap. It proves read volume without resting every row.
+ */
+interface DbReadBulkEventData {
+    engine: DbEngine;
+    table: string;
+    requestId: string;
+    rowCount: number;
+    emittedRows: number;
+    truncatedRows: number;
+    samplePks: Array<Record<string, unknown>>;
+}
+type InteractionElementDescriptor = Record<string, unknown>;
+type InteractionElementDescriptorFactory = (element: Element) => InteractionElementDescriptor;
+/**
+ * Declarative environment input the host app passes to `logger.setEnv`. Both fields are
+ * vendor-agnostic free-form maps (no LaunchDarkly/PostHog adapters). Values are redacted
+ * through the browser redaction policy before they rest in any `k:'env'` event.
+ */
+interface EnvDeclaration {
+    /** Active feature flags, e.g. `{ newCheckout: true, plan: 'pro' }`. */
+    flags?: Record<string, unknown>;
+    /** Runtime config the app wants attached to the session, e.g. `{ region: 'eu' }`. */
+    config?: Record<string, unknown>;
+}
+/**
+ * Redaction-aware environment snapshot captured once at session start (the `d` payload of a
+ * `k:'env'` event with `kind:'snapshot'`). Browser/device fields are best-effort and guarded
+ * for non-browser/SSR runtimes; `locale`/`timezone` are available in Node via `Intl`.
+ */
+interface EnvSnapshot {
+    /** Discriminates the initial full snapshot from later `setEnv` deltas. */
+    kind: "snapshot" | "delta";
+    userAgent?: string;
+    browser?: {
+        name: string;
+        version?: string;
+    };
+    os?: string;
+    viewport?: {
+        w: number;
+        h: number;
+    };
+    locale?: string;
+    timezone?: string;
+    /** Redacted feature flags declared via `setEnv`. */
+    flags?: Record<string, unknown>;
+    /** Redacted runtime config declared via `setEnv`. */
+    config?: Record<string, unknown>;
+    /** Browser redaction metadata for any redacted flag/config values. */
+    redaction?: unknown;
+}
+interface FlagBugOptions {
+    note?: string;
+    windowMs?: number;
+    tags?: string[];
+    voiceBlob?: Blob;
+}
+interface AddBugEventOptions {
+    type: string;
+    data: Record<string, unknown>;
+    schemaVersion?: BugEvent["schemaVersion"];
+    platform?: BugEvent["platform"];
+    sdk?: BugEvent["sdk"];
+    capabilities?: BugEvent["capabilities"];
+    target?: BugEvent["target"];
+    sessionId?: BugEvent["sessionId"];
+    offsetMs?: BugEvent["offsetMs"];
+}
+interface CrumbtrailConfig {
+    console: boolean;
+    network: boolean;
+    interactions: boolean;
+    keystrokes: boolean;
+    scroll: boolean;
+    visibility: boolean;
+    clipboard: boolean;
+    errors: boolean;
+    performance: boolean;
+    cookies: boolean;
+    storage: boolean;
+    video: boolean;
+    audio: boolean;
+    networkMaxBodySize: number;
+    networkExcludeUrls: string[];
+    networkCaptureHeaders: boolean;
+    networkCorrelationHeaders: boolean;
+    networkCorrelationAllowedOrigins: string[];
+    maskInputTypes: string[];
+    ignoreSelectors: string[];
+    describeInteractionElement?: InteractionElementDescriptorFactory;
+    keystrokeThrottleMs: number;
+    scrollThrottleMs: number;
+    scrollElements: string[];
+    clipboardMaxLength: number;
+    captureRawClipboard: boolean;
+    cookiePollIntervalMs: number;
+    cookieMaskNames: string[];
+    cookieValueMaxLength: number;
+    storageValueMaxLength: number;
+    storageExcludeKeys: string[];
+    captureIdb: boolean;
+    captureCacheApi: boolean;
+    videoBitsPerSecond: number;
+    audioBitsPerSecond: number;
+    mediaChunkIntervalMs: number;
+    ringBufferMs: number;
+    ringBufferMaxEvents: number;
+    heartbeat: boolean;
+    environment: boolean;
+    widget: boolean;
+    stateMaxBytes: number;
+    captureRawState: boolean;
+    autoFlagOnError: boolean;
+    autoFlagDebounceMs: number;
+    autoFlagMaxPerSession: number;
+    autoFlagOnSignals: boolean;
+    rageClickThreshold: number;
+    rageClickWindowMs: number;
+    retryStormThreshold: number;
+    retryStormWindowMs: number;
+    retryStormFailThreshold: number;
+    slowRequestMs: number;
+    slowRequestCount: number;
+    slowRequestWindowMs: number;
+    abandonedFlowWindowMs: number;
+    abandonedFlowMinInputs: number;
+    domSnapshot: boolean;
+    domSnapshotMaxBytes: number;
+    captureRawConsole: boolean;
+    captureRawErrors: boolean;
+    transport: "auto" | "tauri" | "http";
+    transportInstance?: CrumbtrailTransport;
+    httpEndpoint: string;
+    httpAuthToken?: string;
+    flushIntervalMs: number;
+    flushBufferSize: number;
+    sendBlob?: (name: string, blob: Blob) => void;
+    sessionPersistence: "session" | "memory" | "none";
+    sessionIdleMs: number;
+    sessionId?: string;
+    sessionStore?: SessionStore;
+}
+declare const DEFAULT_CONFIG: CrumbtrailConfig;
+type CrumbtrailPreset = "full" | "light" | "passive";
+declare const PRESET_FULL: Partial<CrumbtrailConfig>;
+declare const PRESET_LIGHT: Partial<CrumbtrailConfig>;
+declare const PRESET_PASSIVE: Partial<CrumbtrailConfig>;
+type CollectorCleanup = () => void;
+interface CollectorContext {
+    sessionId: string;
+    /**
+     * Returns env declared via `setEnv` before the snapshot is emitted so the environment
+     * collector can fold it into the initial `k:'env'` snapshot. Absent for other collectors.
+     */
+    getDeclaredEnv?: () => EnvDeclaration;
+    /** Called by the environment collector once the initial snapshot has been emitted. */
+    onEnvEmitted?: () => void;
+    /**
+     * Lets a collector expose live diagnostic state (e.g. in-flight requests) that is snapshotted
+     * at flag time through the same redaction/truncation path as app state providers.
+     */
+    registerStateProvider?: (name: string, provider: () => unknown) => () => void;
+}
+interface CrumbtrailTransport {
+    sendEvents(events: BugEvent[]): Promise<void>;
+    sendBlob(name: string, blob: Blob, metadata?: Record<string, unknown>): Promise<void>;
+    startSession(sessionId: string, metadata: Record<string, unknown>): Promise<void>;
+    endSession(sessionId: string): Promise<void>;
+    sendBugReport(report: BugReport, events: BugEvent[], voiceBlob?: Blob): Promise<void>;
+}
+
+declare class Crumbtrail {
+    private bus;
+    private transport;
+    private ringBuffer;
+    private cleanups;
+    private config;
+    private sessionId;
+    private widgetCleanup?;
+    private stateProviders;
+    private declaredFlags;
+    private declaredConfig;
+    private envEmitted;
+    private constructor();
+    static init(presetOrConfig?: CrumbtrailPreset | Partial<CrumbtrailConfig>): Crumbtrail;
+    flagBug(options?: FlagBugOptions): Promise<{
+        bugId: string;
+    }>;
+    mark(label: string): void;
+    addEvent(partial: AddBugEventOptions): void;
+    getSessionId(): string;
+    createRequestHeaders(requestId?: string): Record<string, string>;
+    pause(): void;
+    resume(): void;
+    registerStateProvider(name: string, provider: () => unknown): () => void;
+    /**
+     * Declaratively attach vendor-agnostic feature flags / config to the session environment.
+     * Values are redacted before they rest. Merges into the declared env; if the initial
+     * `k:'env'` snapshot has already been emitted (the normal case, since `setEnv` is called
+     * after `init`), it emits a `k:'env'` delta event ({ kind:'delta' }). If called before the
+     * snapshot is emitted (e.g. environment collector disabled or not yet run), the values are
+     * folded into the snapshot instead.
+     */
+    setEnv(declaration: EnvDeclaration): void;
+    stop(): Promise<{
+        sessionId: string;
+    }>;
+}
+
+declare class EventBus {
+    private listeners;
+    private taps;
+    private buffer;
+    private flushTimer;
+    private paused;
+    private flushBufferSize;
+    emit(event: BugEvent): void;
+    /**
+     * Observe every event synchronously at emit time, before batching. Unlike `subscribe`,
+     * taps see events immediately (triggers can't wait out a flush interval) and never
+     * receive batches.
+     */
+    tap(fn: (event: BugEvent) => void): () => void;
+    subscribe(fn: (events: BugEvent[]) => void): () => void;
+    flush(): void;
+    start(flushIntervalMs: number, flushBufferSize: number): void;
+    stop(): void;
+    pause(): void;
+    resume(): void;
+}
+
+declare class RingBuffer {
+    private events;
+    private maxMs;
+    private maxEvents;
+    constructor(maxMs?: number, maxEvents?: number);
+    push(event: BugEvent): void;
+    pushBatch(events: BugEvent[]): void;
+    snapshot(windowMs?: number): BugEvent[];
+    clear(): void;
+    get size(): number;
+    private evict;
+}
+
+interface HttpTransportOptions {
+    authToken?: string;
+}
+declare class HttpTransport implements CrumbtrailTransport {
+    private sessionId;
+    private authToken?;
+    private endpoint;
+    constructor(endpoint: string, options?: HttpTransportOptions);
+    private withAuthHeaders;
+    sendEvents(events: BugEvent[]): Promise<void>;
+    sendBlob(name: string, blob: Blob, metadata?: Record<string, unknown>): Promise<void>;
+    startSession(sessionId: string, metadata: Record<string, unknown>): Promise<void>;
+    sendBugReport(report: BugReport, events: BugEvent[], voiceBlob?: Blob): Promise<void>;
+    endSession(sessionId: string): Promise<void>;
+}
+
+/**
+ * Converts a runtime-specific target object into the shared, privacy-safe target descriptor.
+ * Mobile SDKs can implement this against native view metadata without depending on DOM APIs.
+ */
+interface TargetDescriptorResolver<TTarget = unknown> {
+    resolve(target: TTarget): TargetDescriptor | undefined;
+}
+declare class WebTargetDescriptorResolver implements TargetDescriptorResolver<Element> {
+    resolve(element: Element): TargetDescriptor | undefined;
+}
+declare const webTargetDescriptorResolver: WebTargetDescriptorResolver;
+
+declare const BROWSER_REDACTION_POLICY = "crumbtrail.browser-redaction.v1";
+declare const REDACTED_VALUE = "[REDACTED]";
+declare const REDACTED_STORAGE_KEY = "[REDACTED_KEY]";
+type RedactionAction = "redacted" | "dropped" | "summarized";
+interface RedactionField {
+    path: string;
+    reason: string;
+    action: RedactionAction;
+}
+interface PayloadSummary {
+    kind: "json" | "text" | "form" | "binary" | "stream" | "storage" | "cookie" | "input" | "unknown";
+    action: RedactionAction;
+    reason: string;
+    originalLength?: number;
+    contentLength?: string;
+    limit?: number;
+    redactedFields?: number;
+}
+interface RedactionMetadata {
+    policy: typeof BROWSER_REDACTION_POLICY;
+    fields: RedactionField[];
+    summaries?: PayloadSummary[];
+}
+interface RedactionResult<T> {
+    value: T;
+    metadata?: RedactionMetadata;
+    summary?: PayloadSummary;
+}
+interface BodyRedactionResult {
+    body?: string;
+    bodySummary?: PayloadSummary;
+    metadata?: RedactionMetadata;
+}
+interface BodyRedactionOptions {
+    contentType?: string | null;
+    maxLength?: number;
+    path?: string;
+}
+interface StoredValueRedactionOptions {
+    key?: string;
+    maxLength?: number;
+    path?: string;
+}
+interface InputValueRedactionOptions {
+    name?: string;
+    type?: string;
+    path?: string;
+}
+declare function mergeRedactionMetadata(...items: Array<RedactionMetadata | undefined>): RedactionMetadata | undefined;
+declare function attachRedactionMetadata(target: Record<string, unknown>, ...items: Array<RedactionMetadata | undefined>): void;
+declare function redactTokenLikeString(value: string, path?: string): RedactionResult<string>;
+declare function redactUrl(url: string, path?: string): RedactionResult<string>;
+/**
+ * Scrub secrets from `http(s)://…` URL substrings embedded in FREE TEXT, reusing
+ * the SAME query-key-aware policy {@link redactUrl} applies to `ref.url`.
+ *
+ * The token-shape patterns in {@link redactTokenLikeString} catch Bearer/JWT/
+ * prefixed/long-hex/long-alnum secrets, but MISS a short/medium secret carried as
+ * a URL query param (`?token=abc123def456`, ~12–26 chars) — while `redactUrl` is
+ * query-aware and drops every query value. This finds each URL substring and runs
+ * it through `redactUrl`, so a tokenized URL sitting in an adapter's `after`/
+ * `brief`/gap text loses its query secret while keeping its origin + path as
+ * provenance. Non-URL text is left untouched (fast-path bail when no `://`).
+ *
+ * This shares one implementation with `ref.url` redaction — there is no second
+ * URL-redaction policy.
+ */
+declare function redactUrlsInText(value: string, path?: string): RedactionResult<string>;
+declare function redactHeaders(headers: Record<string, string>, path?: string): RedactionResult<Record<string, string>>;
+declare function redactCookieValue(name: string, value: string, path?: string, configuredMaskNames?: string[]): RedactionResult<string>;
+declare function redactCookieName(name: string): string;
+declare function redactCookieMap(cookies: Record<string, string>, path?: string, configuredMaskNames?: string[]): RedactionResult<Record<string, string>>;
+/**
+ * Redacts an arbitrary JSON-like value (object/array/scalar) through the browser redaction
+ * policy: sensitive-looking key names are masked and token-like string values are scrubbed.
+ * Used to sanitize declarative env flags/config before they rest in a `k:'env'` event.
+ */
+declare function redactValue<T>(value: T, path?: string): RedactionResult<T>;
+declare function redactNetworkTextBody(body: string, options?: BodyRedactionOptions): BodyRedactionResult;
+declare function summarizeBinaryPayload(contentType: string | null | undefined, contentLength: string | null | undefined, path?: string): BodyRedactionResult;
+declare function summarizeOmittedPayload(reason: "stream_payload" | "body_read_failed" | "non_text_request_body", path?: string): BodyRedactionResult;
+declare function redactStorageKey(key: string, path?: string): RedactionResult<string>;
+declare function redactStoredValue(value: string | null | undefined, options?: StoredValueRedactionOptions): RedactionResult<string | undefined>;
+declare function redactInputValue(value: string, options?: InputValueRedactionOptions): RedactionResult<string>;
+
+declare const CRUMBTRAIL_SESSION_HEADER: "X-Crumbtrail-Session-Id";
+declare const CRUMBTRAIL_REQUEST_HEADER: "X-Crumbtrail-Request-Id";
+declare const CRUMBTRAIL_SESSION_HEADER_LOWER: string;
+declare const CRUMBTRAIL_REQUEST_HEADER_LOWER: string;
+declare const CRUMBTRAIL_REQUEST_ID_MAX_LENGTH = 64;
+declare function generateRequestId(): string;
+declare function createCrumbtrailRequestHeaders(sessionId: string, requestId?: string): Record<typeof CRUMBTRAIL_SESSION_HEADER | typeof CRUMBTRAIL_REQUEST_HEADER, string>;
+declare const W3C_TRACEPARENT_HEADER: "traceparent";
+interface W3CTraceContext {
+    traceId: string;
+    spanId: string;
+    flags: number;
+}
+declare function parseTraceparent(value: string | undefined): W3CTraceContext | undefined;
+declare function formatTraceparent(ctx: W3CTraceContext): string;
+/** 16-byte (32 hex) W3C trace id; never all-zero. */
+declare function generateTraceId(): string;
+/** 8-byte (16 hex) W3C span id; never all-zero. */
+declare function generateSpanId(): string;
+/** Fresh, sampled W3C trace context the browser controls. */
+declare function generateTraceContext(): W3CTraceContext;
+interface OutboundCorrelation {
+    sessionId: string;
+    /** Unified correlation key. Equals `traceId` unless the caller pinned a request id. */
+    requestId: string;
+    traceId: string;
+    spanId: string;
+    /** Spec-valid `traceparent` value to emit on the outbound request. */
+    traceparent: string;
+}
+/**
+ * Decides whether Crumbtrail may stamp outbound correlation headers.
+ *
+ * Same-origin requests are allowed automatically. Cross-origin requests must match an
+ * explicit backend-origin allowlist so the default does not trigger CORS preflights or
+ * leak trace context to third-party services.
+ */
+declare function canInjectCorrelationHeaders(requestUrl: string, allowedOrigins?: readonly string[]): boolean;
+/**
+ * Resolves the correlation identity for one outbound request.
+ *
+ * - If the caller already set a valid `traceparent` (an app doing W3C propagation),
+ *   we adopt its trace context so we join on the user's existing trace.
+ * - Otherwise we mint a fresh sampled trace context.
+ *
+ * The trace id doubles as the Crumbtrail request id (`X-Crumbtrail-Request-Id`), so the
+ * native Express path and the OTLP `traceId → requestId` bridge join on one shared key.
+ * An explicit caller-provided request id is honored as-is for backwards compatibility.
+ */
+declare function resolveOutboundCorrelation(input: {
+    sessionId: string;
+    existingRequestId?: string;
+    existingTraceparent?: string;
+}): OutboundCorrelation;
+
+/**
+ * Environment collector. Emits exactly one `k:'env'` snapshot event at session start with a
+ * redaction-aware view of the runtime: userAgent/browser/os/viewport (best-effort, browser
+ * only) plus locale/timezone (available in Node via `Intl`). Any feature flags / config the
+ * app declared via `logger.setEnv` before the snapshot is folded in (redacted). Guarded so it
+ * never throws in non-browser/SSR/test runtimes — it degrades to whatever IS available.
+ *
+ * Out of scope (CP3): privileged enumeration of installed browser extensions (absent in SDK
+ * mode) and continuous mid-session env polling beyond this snapshot + `setEnv` deltas.
+ */
+declare function environmentCollector(bus: EventBus, _config: CrumbtrailConfig, context: CollectorContext): CollectorCleanup;
+/** Builds the redaction-aware snapshot payload. Exported for direct unit testing. */
+declare function buildEnvSnapshot(flags?: Record<string, unknown>, config?: Record<string, unknown>): EnvSnapshot;
+/**
+ * Builds a `k:'env'` delta payload from a `setEnv` call made after the snapshot was emitted.
+ * Values are redacted before they rest. Exported for direct unit testing.
+ */
+declare function buildEnvDelta(flags?: Record<string, unknown>, config?: Record<string, unknown>): EnvSnapshot;
+
+interface ElementSignature {
+    /** Deterministic structural path from a uniquely-identified ancestor (or root) to the element. */
+    path: string;
+    /** Short stable hash of `path` — the element's identity across sessions. */
+    sig: string;
+}
+/** Build a deterministic path, stopping early at the first uniquely-identified ancestor. */
+declare function computeElementPath(el: Element): string;
+/** FNV-1a 32-bit, rendered base36. Deterministic, dependency-free. */
+declare function hashString(input: string): string;
+declare function computeElementSignature(el: Element): ElementSignature;
+
+/**
+ * Shared evidence contract. Both crumbtrail-node (compare engine) and
+ * crumbtrail-cloud (fusion/ranking) speak this. Evidence is neutral and
+ * complete — no ranking or opinion lives here.
+ */
+declare const EVIDENCE_SCHEMA_VERSION: "evidence.v1";
+type EvidenceLane = "flow" | "network" | "db" | "env" | "browser" | "logs" | "memory" | "code";
+interface EvidenceRef {
+    sessionId?: string;
+    requestId?: string;
+    table?: string;
+    pk?: Record<string, unknown>;
+    sig?: string;
+    /**
+     * Provider deep-link back to the source system (Sentry issue URL, CloudWatch
+     * Logs Insights link, etc.) so a human can verify provenance. Shared by every
+     * evidence adapter. A URL carrying an embedded token/credential is scrubbed at
+     * the redaction boundary (see node `redact.ts`); a plain issue URL survives as
+     * provenance. Optional and additive — session-derived evidence omits it.
+     */
+    url?: string;
+    /** Source provider id for a deep-linked item, e.g. "sentry" | "cloudwatch". */
+    provider?: string;
+    /** Provider-native record id for the deep-linked item (issue id, event id). */
+    id?: string;
+}
+interface EvidenceItem {
+    /** Stable id used by IntentSignal.evidenceId to correlate. */
+    id: string;
+    lane: EvidenceLane;
+    /** Discriminating kind, e.g. "net.status", "db.row-value", "flow.step-missing". */
+    kind: string;
+    brief: string;
+    ref: EvidenceRef;
+    before: unknown;
+    after: unknown;
+    /** ms epoch when observed, if known. */
+    whenObserved?: number;
+}
+interface IntentSignal {
+    /** Foreign key to EvidenceItem.id. */
+    evidenceId: string;
+    explainedByCommit?: {
+        sha: string;
+        pr?: string;
+        message: string;
+    };
+    prIntent?: string;
+}
+
+/** A commit range on a git host (e.g. a release tag pair). */
+interface GitHostRef {
+    baseRef: string;
+    headRef: string;
+}
+/** A single commit in a compared range, as reported by a git host. */
+interface CommitInfo {
+    sha: string;
+    message: string;
+    pr?: string;
+    files: string[];
+}
+/** Correlates behavior-change evidence to git-host commits. No network. */
+interface GitHostClient {
+    /** Commits in (baseRef, headRef] that touch the repo. Implementations may prefilter. */
+    listCommits(ref: GitHostRef): Promise<CommitInfo[]>;
+}
+/**
+ * Pure correlation: an evidence item is "explained" when a commit in range
+ * plausibly caused it, via either of two paths:
+ *  - STRONG: an evidence identity token (table name or a brief's route
+ *    segment, minus structural noise) appears among the commit's
+ *    file-path tokens (minus structural noise). A single such match
+ *    qualifies.
+ *  - WEAK (fallback): total shared tokens across all evidence fields and
+ *    all commit fields (message + file paths) is >= MIN_SHARED.
+ * The best commit per evidence item is the one with the highest
+ * (strong-match-count * 100 + weak-shared-count), ties broken by
+ * lexicographically smallest sha. Deterministic, never throws. Returns
+ * signals in the input evidence order.
+ */
+declare function inferIntent(evidence: EvidenceItem[], commits: CommitInfo[]): IntentSignal[];
+
+/**
+ * A leading indicator that a session is going wrong, raised by a {@link SignalDetector}.
+ * The controller turns a raised signal into an auto-flagged report.
+ */
+interface Signal {
+    /** Tag applied to the auto-flagged report, e.g. `"auto:rage-click"`. */
+    tag: string;
+    /** Dedup key — a given key auto-flags at most once per session. */
+    key: string;
+    /** Human-readable note attached to the report. */
+    note: string;
+}
+/**
+ * Inspects the live event stream and raises a {@link Signal} the moment a leading
+ * indicator trips. Detectors are stateful (they track rolling windows) and pure of
+ * side effects — they never flag directly; the controller owns coalescing and caps.
+ */
+interface SignalDetector {
+    inspect(event: BugEvent): Signal | null;
+}
+/** Stable signature for an `err`/`rej` event, from its kind, message, and top stack frames. */
+declare function errorSignature(event: BugEvent): string;
+/**
+ * Reactive baseline detector: an uncaught error or unhandled rejection. Each distinct error
+ * signature flags once per session (dedup is enforced by the controller via {@link Signal.key}).
+ */
+declare function errorDetector(): SignalDetector;
+interface RageClickOptions {
+    /** Clicks on the same target within `windowMs` required to trip. */
+    threshold: number;
+    windowMs: number;
+}
+/**
+ * Precognitive detector: the user hammering the same control (a dead button, a stuck submit)
+ * is a silent failure that throws no error. Trips after `threshold` clicks on one target
+ * inside `windowMs`, then resets that target's window.
+ */
+declare function rageClickDetector(opts: RageClickOptions): SignalDetector;
+interface RetryStormOptions {
+    /** Requests to the same endpoint within `windowMs` required to trip. */
+    threshold: number;
+    windowMs: number;
+    /** Failed responses (status >= 400) to the same endpoint within `windowMs` required to trip. Defaults to 2. */
+    failThreshold?: number;
+}
+declare function retryStormDetector(opts: RetryStormOptions): SignalDetector;
+interface SlowResponseOptions {
+    /** A response is "slow" at or above this duration in ms. */
+    thresholdMs: number;
+    /** Slow responses within `windowMs` required to trip. */
+    count: number;
+    windowMs: number;
+}
+/**
+ * Precognitive detector: a session where responses are piling up slow is degrading before any
+ * timeout throws. Trips after `count` responses at or above `thresholdMs` inside `windowMs`.
+ * Session-scoped (not per-endpoint) so it stays allocation-light — the captured events carry the
+ * per-request detail. Flags once per session (dedup key is stable); the per-session cap bounds it.
+ */
+declare function slowResponseDetector(opts: SlowResponseOptions): SignalDetector;
+interface AbandonedFlowOptions {
+    /** Max ms from the last input to a page-hide that still counts as abandonment. */
+    windowMs: number;
+    /** Minimum input events before an interaction is treated as a "flow" worth flagging. */
+    minInputs: number;
+}
+/**
+ * Precognitive detector: the user filled a form, then left (hid/closed the tab) without submitting
+ * — a silent abandonment that throws nothing and never reaches support. Trips when the page is
+ * hidden within `windowMs` of the last of at least `minInputs` inputs, with no mutating request
+ * (submit) in between. A mutating `net.req` clears the pending flow. Flags once per session.
+ */
+declare function abandonedFlowDetector(opts: AbandonedFlowOptions): SignalDetector;
+
+interface AutoFlagOptions {
+    /** Quiet period after the last new signal before the flag fires, so a cascade coalesces into one report. */
+    debounceMs: number;
+    /** Hard cap on auto-captured reports per session (shared across all detectors). */
+    maxPerSession: number;
+    flag: (options: FlagBugOptions) => Promise<unknown>;
+    /**
+     * Signal detectors that decide when to auto-flag. Defaults to error-only (`errorDetector`),
+     * preserving the original reactive-on-error behavior. Pass behavioral detectors
+     * (rage-click, retry-storm, …) to capture silent failures before an error throws.
+     */
+    detectors?: SignalDetector[];
+}
+interface AutoFlagController {
+    handleEvent(event: BugEvent): void;
+    dispose(): void;
+}
+/**
+ * Turns raised {@link Signal}s into automatic `flagBug` snapshots. Each signal key is flagged
+ * once per session, and a burst of signals settles into a single report (the debounce doubles
+ * as post-roll so the ring buffer snapshot includes the cascade's aftermath). The first signal
+ * to open a debounce window owns the report's tag and note; the total report count is capped by
+ * `maxPerSession` across every detector.
+ */
+declare function createAutoFlagController(options: AutoFlagOptions): AutoFlagController;
+
+/**
+ * @stability stable
+ * Version-bump policy (additive-on-v1 vs fusion.v2) is War-game 01 Fork A's
+ * decision, not this file's — see wargames/wargames/01-solve-context-wargame-fields.md.
+ */
+declare const FUSION_SCHEMA_VERSION: "fusion.v1";
+type HypothesisKind = "regression" | "latent" | "environment" | "client-side" | "intentional-change" | "inconclusive";
+interface Symptom {
+    title: string;
+    description?: string;
+    release?: string;
+    url?: string;
+    user?: string;
+    errorSig?: string;
+    source?: string;
+}
+interface Hypothesis {
+    kind: HypothesisKind;
+    /** 0..1 advisory confidence. Not a probability; a ranking signal. */
+    confidence: number;
+    rationale: string;
+    /** EvidenceItem.id values backing this hypothesis. */
+    evidenceIds: string[];
+}
+interface EvidenceGap {
+    lane: EvidenceLane;
+    reason: string;
+    suggestion?: string;
+    /**
+     * Optional structured severity marker. Additive and defaults to an ordinary
+     * informational gap when absent (e.g. a missing join key, or a partial
+     * enrichment/secondary gap) — those never affect a source's health.
+     *
+     * `"source-unavailable"` marks a HARD failure: the adapter could not deliver
+     * its primary evidence at all (dispatch/auth failure, or a timeout that
+     * retrieved zero items) and self-degraded to a gap instead of throwing. The
+     * evidence framework reads this typed marker — never the free-text `reason` —
+     * to decide `stats.ok`, so a self-degrading source and a throwing source emit
+     * the same health signal. See node `fetch-all.ts`.
+     */
+    kind?: "source-unavailable";
+}
+interface CaptureDirective {
+    /** The bug signature this raises capture for. */
+    signature: string;
+    /** Lanes to collect more deeply next time. */
+    raise: EvidenceLane[];
+    scope: "signature" | "session";
+    reason: string;
+}
+interface RankedBundle {
+    schemaVersion: typeof FUSION_SCHEMA_VERSION;
+    symptom: Symptom;
+    /** Complete, neutral evidence in ranked order. Never filtered. */
+    evidence: EvidenceItem[];
+    /** Advisory only. Consumers may ignore and use evidence directly. */
+    opinion: {
+        stance: "advisory";
+        hypotheses: Hypothesis[];
+    };
+    gaps: EvidenceGap[];
+    /** Advisory-only: suggested capture escalations when evidence is thin. */
+    directives: CaptureDirective[];
+}
+interface AssembleBundleInput {
+    symptom: Symptom;
+    evidence: EvidenceItem[];
+    intent: IntentSignal[];
+    gaps?: EvidenceGap[];
+}
+/**
+ * Compose the RankedBundle: rank the complete evidence set (nothing dropped),
+ * classify advisory hypotheses, and pass through any evidence gaps. Pure.
+ */
+declare function assembleBundle(input: AssembleBundleInput): RankedBundle;
+
+/**
+ * Provider-agnostic evidence-source contract (types only — browser-safe, no I/O).
+ *
+ * This is the query-at-incident-time pull surface: when a ticket arrives, the
+ * runtime asks a client's existing observability tools (Sentry, CloudWatch,
+ * Splunk, Datadog, PostHog, Cloudflare) for evidence inside the located incident
+ * window and normalizes each hit into the neutral `evidence.v1` contract
+ * ({@link EvidenceItem} / {@link EvidenceGap}). Evidence stays neutral and
+ * complete here — ranking/opinion happens exactly once downstream in
+ * `assembleBundle` (fusion.v1), never in adapter output.
+ *
+ * Deliberately distinct from the OTLP dual-export path: adapters are zero-copy
+ * and derived-artifacts-only; only the assembled bundle persists.
+ */
+
+/**
+ * Schema version string const, matching the repo convention
+ * (`evidence.v1` / `fusion.v1` / `fix-context.v1`).
+ */
+declare const EVIDENCE_SOURCE_SCHEMA_VERSION: "evidence-source.v1";
+/**
+ * Correlation keys an adapter can filter by. The Varicent lesson: most clients
+ * do not propagate a trace end-to-end, so an adapter must declare (in its
+ * descriptor) which keys it can actually use and honestly report — via an
+ * {@link EvidenceGap} — when a requested key is unavailable and it fell back to
+ * a time window only. Note `traceId` doubles as `requestId` in the repo's
+ * correlation model.
+ */
+type EvidenceJoinKey = "traceId" | "requestId" | "sessionId" | "time" | "release" | "url" | "user" | "service";
+interface EvidenceSourceDescriptor {
+    /** Stable provider id, e.g. "sentry" | "cloudwatch" | "splunk". */
+    provider: string;
+    /** Human-facing name for doctor output and docs. */
+    displayName: string;
+    /** Which evidence.v1 lanes this source can populate. */
+    lanes: EvidenceLane[];
+    /** Keys it can actually filter by, best-first (drives query construction). */
+    joinKeys: EvidenceJoinKey[];
+    /** Env-var names carrying this source's credentials, for doctor + docs. */
+    authFields: string[];
+}
+interface EvidenceQuery {
+    /** ms-epoch incident window, already located upstream. */
+    window: {
+        start: number;
+        end: number;
+    };
+    /** Correlation keys known for this incident; adapters use what they support. */
+    keys: Partial<Record<EvidenceJoinKey, string>>;
+    /** fusion.v1 Symptom, for text-relevance hints (optional). */
+    symptom?: Symptom;
+    /** Egress + token discipline: hard bounds every adapter must honor. */
+    limits: {
+        maxItems: number;
+        maxBytes: number;
+        timeoutMs: number;
+    };
+}
+interface EvidenceSourceResult {
+    schemaVersion: typeof EVIDENCE_SOURCE_SCHEMA_VERSION;
+    /** Neutral evidence.v1 items — no ranking, no opinion. */
+    items: EvidenceItem[];
+    /** e.g. "splunk cannot filter by traceId; used time window only". */
+    gaps: EvidenceGap[];
+    stats: {
+        provider: string;
+        fetched: number;
+        returned: number;
+        truncated: boolean;
+        latencyMs: number;
+    };
+}
+
+export { type AbandonedFlowOptions, type AddBugEventOptions, type AssembleBundleInput, type AutoFlagController, type AutoFlagOptions, BROWSER_REDACTION_POLICY, type BodyRedactionOptions, type BodyRedactionResult, type BugEvent, type BugReport, CRUMBTRAIL_EVENT_KINDS, CRUMBTRAIL_REQUEST_HEADER, CRUMBTRAIL_REQUEST_HEADER_LOWER, CRUMBTRAIL_REQUEST_ID_MAX_LENGTH, CRUMBTRAIL_SCHEMA_VERSION, CRUMBTRAIL_SESSION_HEADER, CRUMBTRAIL_SESSION_HEADER_LOWER, type CaptureDirective, type CollectorCleanup, type CollectorContext, type CommitInfo, Crumbtrail, type CrumbtrailCapabilities, type CrumbtrailConfig, type CrumbtrailPlatform, type CrumbtrailPreset, type CrumbtrailSdkDescriptor, type CrumbtrailTransport, DB_DIFF_BULK_EVENT_KIND, DB_DIFF_EVENT_KIND, DB_READ_BULK_EVENT_KIND, DB_READ_EVENT_KIND, DEFAULT_CONFIG, DEFAULT_SESSION_STORAGE_KEY, type DbDiffBulkEventData, type DbDiffEventData, type DbDiffOp, type DbEngine, type DbReadBulkEventData, type DbReadEventData, EVIDENCE_SCHEMA_VERSION, EVIDENCE_SOURCE_SCHEMA_VERSION, type ElementSignature, type EnvDeclaration, type EnvSnapshot, EventBus, type EvidenceGap, type EvidenceItem, type EvidenceJoinKey, type EvidenceLane, type EvidenceQuery, type EvidenceRef, type EvidenceSourceDescriptor, type EvidenceSourceResult, FUSION_SCHEMA_VERSION, type FlagBugOptions, type GitHostClient, type GitHostRef, HttpTransport, type Hypothesis, type HypothesisKind, type InputValueRedactionOptions, type IntentSignal, type InteractionElementDescriptor, type InteractionElementDescriptorFactory, type OutboundCorrelation, PRESET_FULL, PRESET_LIGHT, PRESET_PASSIVE, type PayloadSummary, type PersistedSession, REDACTED_STORAGE_KEY, REDACTED_VALUE, type RageClickOptions, type RankedBundle, type RedactionAction, type RedactionField, type RedactionMetadata, type RedactionResult, type RetryStormOptions, RingBuffer, type SessionStore, type Signal, type SignalDetector, type SlowResponseOptions, type StoredValueRedactionOptions, type Symptom, type TargetDescriptor, type TargetDescriptorResolver, type W3CTraceContext, W3C_TRACEPARENT_HEADER, WebTargetDescriptorResolver, abandonedFlowDetector, assembleBundle, attachRedactionMetadata, buildEnvDelta, buildEnvSnapshot, canInjectCorrelationHeaders, computeElementPath, computeElementSignature, createAutoFlagController, createCrumbtrailRequestHeaders, createWebSessionStore, environmentCollector, errorDetector, errorSignature, formatTraceparent, generateRequestId, generateSpanId, generateTraceContext, generateTraceId, hashString, inferIntent, mergeRedactionMetadata, parseTraceparent, rageClickDetector, redactCookieMap, redactCookieName, redactCookieValue, redactHeaders, redactInputValue, redactNetworkTextBody, redactStorageKey, redactStoredValue, redactTokenLikeString, redactUrl, redactUrlsInText, redactValue, resolveOutboundCorrelation, retryStormDetector, slowResponseDetector, summarizeBinaryPayload, summarizeOmittedPayload, webTargetDescriptorResolver };