crumbtrail-node 0.1.0

package/dist/index.d.cts

@@ -0,0 +1,2798 @@
+import http from 'node:http';
+import { Symptom, EvidenceSourceDescriptor, EvidenceQuery, EvidenceSourceResult, DbEngine, TargetDescriptor, BugEvent, EvidenceItem, IntentSignal, EvidenceGap, EvidenceJoinKey, GitHostClient, DbDiffOp } from 'crumbtrail-core';
+export { EvidenceJoinKey, EvidenceSourceDescriptor } from 'crumbtrail-core';
+
+type TicketProvider = "jira" | "zendesk" | "trello";
+declare function jiraToSymptom(payload: unknown): Symptom;
+
+interface TicketConnector {
+    fetchSymptom(id: string): Promise<Symptom>;
+}
+/**
+ * Extension of TicketConnector for providers that can write an advisory
+ * comment back to the ticket. Declared as a separate interface (not an
+ * optional method on TicketConnector) so read-only connectors stay honest and
+ * callers that need commenting — the cloud webhook writer — type against the
+ * capability explicitly (contract decision #10).
+ */
+interface CommentingTicketConnector extends TicketConnector {
+    postComment(ticketKey: string, adfBody: unknown, retry?: BoundedRetryOptions): Promise<void>;
+}
+/** Thrown when a ticket provider REST call fails, or required env config is missing (status 0). */
+declare class TicketError extends Error {
+    status: number;
+    constructor(status: number, message: string);
+}
+/**
+ * Source-identification User-Agent sent on EVERY outbound integration request.
+ * Atlassian's third-party app guidance requires apps to "identify their source
+ * transparently"; a stable, descriptive UA is how a Jira/Confluence admin (and
+ * Atlassian's own abuse tooling) can attribute traffic to Crumbtrail. Applied to
+ * Zendesk/Trello too for consistency. Kept version-light on purpose so it does
+ * not churn every release — it identifies the source, not an exact build.
+ */
+declare const CRUMBTRAIL_USER_AGENT = "Crumbtrail/0.1 (+https://crumbtrail.dev; integrations@crumbtrail.dev)";
+/** Options for {@link withBoundedRetry}. All fields optional; production callers
+ *  rely on the defaults, tests inject `baseDelayMs: 0`/a fake `sleep` to run fast. */
+interface BoundedRetryOptions {
+    /** Total attempts (not extra retries). Default 3. */
+    attempts?: number;
+    /** Linear backoff base; the wait before attempt N is `baseDelayMs * (N-1)`. */
+    baseDelayMs?: number;
+    /** Decide whether a thrown error is worth retrying. Default: transient only. */
+    isRetryable?: (error: unknown) => boolean;
+    /** Sleep hook (overridable in tests). Default: real setTimeout. */
+    sleep?: (ms: number) => Promise<void>;
+}
+/**
+ * Run `fn` with a small bounded retry (default 3 attempts, short linear
+ * backoff). Re-throws the last error once attempts are exhausted or the error is
+ * non-retryable. Deliberately tiny — no queue, no jitter; comment posting is the
+ * one caller and a v1 best-effort write.
+ */
+declare function withBoundedRetry<T>(fn: () => Promise<T>, options?: BoundedRetryOptions): Promise<T>;
+/** HTTP Basic auth: Atlassian API token bound to an account email
+ *  (`email:token`, base64). This is the self-host / API-token path. */
+interface JiraBasicAuth {
+    type: "basic";
+    email: string;
+    apiToken: string;
+}
+/** OAuth 3LO bearer auth: a short-lived access token. Per Atlassian, OAuth API
+ *  calls go to `https://api.atlassian.com/ex/jira/{cloudId}` (NOT the
+ *  `*.atlassian.net` site base) with `Authorization: Bearer <accessToken>`; the
+ *  caller sets `baseUrl` accordingly. The client never refreshes — the cloud
+ *  connector boundary hands in an already-valid access token. */
+interface JiraBearerAuth {
+    type: "bearer";
+    accessToken: string;
+}
+type JiraAuth = JiraBasicAuth | JiraBearerAuth;
+/** Legacy positional shape — kept byte-compatible so existing callers
+ *  (ticketClientFromEnv, self-host) construct exactly as before. */
+interface JiraTicketClientConfigLegacy {
+    baseUrl: string;
+    email: string;
+    apiToken: string;
+    fetchImpl?: typeof fetch;
+}
+/** Discriminated-auth shape (basic OR bearer) with an explicit baseUrl. */
+interface JiraTicketClientConfigWithAuth {
+    baseUrl: string;
+    auth: JiraAuth;
+    fetchImpl?: typeof fetch;
+}
+type JiraTicketClientConfig = JiraTicketClientConfigLegacy | JiraTicketClientConfigWithAuth;
+declare class JiraTicketClient implements CommentingTicketConnector {
+    private baseUrl;
+    private auth;
+    private fetchImpl;
+    constructor(config: JiraTicketClientConfig);
+    /** The Authorization header value for the configured auth mode. The secret
+     *  (token/access token) only ever lives inside this header string — it is
+     *  never surfaced in an error message (only sanitized URLs are). */
+    private authHeader;
+    fetchSymptom(id: string): Promise<Symptom>;
+    /**
+     * POST an advisory comment to a Jira issue. `adfBody` is an Atlassian Document
+     * Format doc (see buildAdvisoryComment); it is sent as `{ body: <adf> }`.
+     * Wrapped in a small bounded retry so a transient 5xx/429/network blip does not
+     * drop the comment. Throws TicketError on a non-2xx that survives the retries —
+     * the API token never appears in the message (only the sanitized URL does).
+     */
+    postComment(issueIdOrKey: string, adfBody: unknown, retry?: BoundedRetryOptions): Promise<void>;
+}
+
+/**
+ * Evidence-source framework (runtime half). Mirrors the ticket-connector
+ * pattern in `ticket/clients.ts`: env-var credentials for self-host, a provider
+ * is present ⇔ its required vars are all set, and every outbound request carries
+ * {@link CRUMBTRAIL_USER_AGENT}. Adapters (CP3+) register here; this file is the
+ * contract + presence logic only.
+ */
+/**
+ * Health of one configured source. Emitted by `EvidenceSource.health()` (a
+ * cheap authenticated no-op) and surfaced by `crumbtrail-server doctor`.
+ */
+interface SourceHealth {
+    ok: boolean;
+    provider: string;
+    /** ms epoch when the check ran. */
+    checkedAt: number;
+    /** Sanitized failure reason when `ok` is false (never a raw secret). */
+    error?: string;
+}
+/**
+ * One provider's runtime surface. `fetchEvidence` returns neutral evidence.v1
+ * items (no ranking); it never gates and — through the framework — degrades to
+ * a gap rather than throwing. The optional `signal` lets the framework's
+ * per-source timeout abort an in-flight outbound fetch; adapters should thread
+ * it into their `fetch` calls when present.
+ */
+interface EvidenceSource {
+    readonly descriptor: EvidenceSourceDescriptor;
+    health(signal?: AbortSignal): Promise<SourceHealth>;
+    fetchEvidence(query: EvidenceQuery, signal?: AbortSignal): Promise<EvidenceSourceResult>;
+}
+/**
+ * A registered provider: how to detect its env credentials and construct a
+ * source from them. Adapters append an entry to {@link EVIDENCE_SOURCE_PROVIDERS}.
+ */
+interface EvidenceSourceProvider {
+    provider: string;
+    /**
+     * Required env-var names. The provider is considered configured iff every one
+     * is set to a non-empty string — mirroring `ticketClientFromEnv`'s
+     * present ⇔ required-vars-set rule.
+     */
+    authFields: string[];
+    fromEnv(env: Record<string, string | undefined>): EvidenceSource;
+}
+/**
+ * Provider registry. Adapters (Sentry in CP3, then CloudWatch/Splunk/…) append
+ * their {@link EvidenceSourceProvider} here via {@link registerEvidenceProvider}.
+ * `evidenceSourcesFromEnv` walks it to build the configured sources.
+ */
+declare const EVIDENCE_SOURCE_PROVIDERS: EvidenceSourceProvider[];
+/**
+ * Register a provider once (idempotent by `provider` id). Adapter modules call
+ * this at import time; `../evidence-sources/index.ts` imports every adapter so a
+ * single import of the barrel populates the registry. Idempotency keeps repeated
+ * imports (test isolation, HMR) from double-registering.
+ */
+declare function registerEvidenceProvider(provider: EvidenceSourceProvider): void;
+/**
+ * Build the configured evidence sources from env. A provider is included iff all
+ * its `authFields` are set. Never throws for a partially-configured provider —
+ * it is simply omitted (adapter absence degrades to a gap downstream, never an
+ * error). `providers` is injectable for tests.
+ */
+declare function evidenceSourcesFromEnv(env?: Record<string, string | undefined>, providers?: EvidenceSourceProvider[]): EvidenceSource[];
+/**
+ * Base headers every adapter's outbound request must include. Exposes the
+ * shared source-identifying User-Agent so adapters do not re-declare it.
+ */
+declare function evidenceRequestHeaders(extra?: Record<string, string>): Record<string, string>;
+
+type AudioTranscriptionState = "not-requested" | "transcription-ready" | "transcription-unavailable" | "transcription-error";
+interface PostProcessAudioSummary {
+    artifact: "audio.webm";
+    bytes: number;
+    upload?: {
+        metadataFile: "audio.json";
+        uploadedAt?: number;
+        contentType?: string;
+        mimeType?: string;
+        durationMs?: number;
+        chunkCount?: number;
+        transcriptionRequested?: boolean;
+    };
+    transcription: {
+        state: AudioTranscriptionState;
+        code?: "transcription_unavailable" | "transcription_failed";
+        message?: string;
+        transcriptFile?: "transcript.json";
+        eventCount?: number;
+    };
+}
+
+type Severity = 'critical' | 'high' | 'medium' | 'low';
+interface SessionSummary {
+    id: string;
+    release?: string;
+    build?: string;
+    start: number;
+    end?: number;
+    dur?: number;
+    evts?: number;
+    errors: number;
+    failedReqs: number;
+    topSeverity?: Severity;
+    title?: string;
+    hasVideo: boolean;
+    hasDiagnosis: boolean;
+}
+interface SessionFileFlags {
+    hasVideo: boolean;
+    hasDiagnosis: boolean;
+    topSeverity?: Severity;
+}
+declare function buildSessionSummary(metaJson: unknown, indexJson: unknown, fileFlags: SessionFileFlags): SessionSummary;
+
+interface SessionManagerConfig {
+    outputDir: string;
+    whisperModel?: string;
+    postProcess?: (sessionDir: string, whisperModel?: string) => Promise<void>;
+}
+interface SessionListItem {
+    id: string;
+    release?: string;
+    build?: string;
+    start: number;
+    end?: number;
+}
+interface SessionFinalizationResult {
+    ok: true;
+    sessionId: string;
+    processed: boolean;
+    degraded: boolean;
+    finalizedAt: number;
+    postProcess: {
+        ok: boolean;
+        error?: string;
+        audio?: PostProcessAudioSummary;
+        warnings?: Array<{
+            capability: "audio" | "video";
+            code: string;
+            message: string;
+        }>;
+    };
+}
+declare class SessionManager {
+    private outputDir;
+    private whisperModel?;
+    private postProcess;
+    constructor(config: string | SessionManagerConfig);
+    create(sessionId: string, metadata: Record<string, unknown>): void;
+    getSessionDir(sessionId: string): string;
+    getExistingSessionDir(sessionId: string): string | undefined;
+    private validateSessionId;
+    private resolveInsideOutput;
+    private resolveStagingSessionDir;
+    private assertSafeSessionDir;
+    private findExistingSessionDir;
+    private moveSessionToV2Partition;
+    finalize(sessionId: string, options?: {
+        refinalize?: boolean;
+    }): Promise<SessionFinalizationResult>;
+    private eachSessionDir;
+    list(filters?: {
+        app?: string;
+        after?: number;
+        before?: number;
+        release?: string;
+        build?: string;
+    }): SessionListItem[];
+    listSummaries(): SessionSummary[];
+    private isSessionDir;
+    private ensurePartitionParent;
+    private assertSafeDirectoryInsideOutput;
+    private writeSessionArtifact;
+    private assertNoSymlinkedGeneratedArtifacts;
+}
+
+interface AiDiagnosisConfig {
+    enabled: boolean;
+    apiKey?: string;
+    model?: string;
+    allowAutoModel?: boolean;
+    maxWindows?: number;
+    maxPromptBytes?: number;
+    fetchImpl?: typeof fetch;
+    log?: (message: string) => void;
+    /** Diagnose finalized sessions already on disk when the server starts. */
+    backfillOnStart?: boolean;
+    /** Bounded provider concurrency for startup backfill. Default 2. */
+    backfillConcurrency?: number;
+}
+
+interface ServerConfig {
+    port: number;
+    outputDir: string;
+    whisperModel?: string;
+    /** Override the session finalization post-processing step (e.g. to skip whisper transcription in tests). */
+    postProcess?: SessionManagerConfig["postProcess"];
+    staticDir?: string;
+    authToken?: string;
+    allowedOrigins?: string[];
+    maxJsonBodyBytes?: number;
+    maxEventBatchSize?: number;
+    maxSessionEventBytes?: number;
+    maxBlobBytes?: number;
+    allowRemoteApi?: boolean;
+    ai?: AiDiagnosisConfig;
+    otlpAutoSessionWindowMs?: number;
+    maxOtlpTraceSessionCache?: number;
+    /**
+     * Idle-session sweep: server-side finalization for sessions that never call
+     * POST /api/session/end (autoCapture backends, OTLP auto-sessions). Enabled
+     * by default — without it those sessions never produce index.json and every
+     * dashboard detail read 404s. Set `enabled: false` to opt out (tests).
+     */
+    sessionSweep?: {
+        enabled?: boolean;
+        idleMs?: number;
+        /** Max age before a never-idle (still-active) session is checkpoint-finalized. */
+        checkpointMs?: number;
+        intervalMs?: number;
+        maxPerSweep?: number;
+    };
+    /**
+     * Severity-triggered fast finalize: high-severity ingest events (uncaught
+     * errors/rejections, 5xx, backend errors, OTel ERROR spans/logs) schedule a
+     * debounced checkpoint-finalize for their session, cutting worst-case
+     * detection latency from the idle-sweep cadence (~40 min) to roughly the
+     * debounce window. Enabled by default; set `enabled: false` to opt out
+     * (tests). Scheduler state is in-memory only — a fast finalize lost to a
+     * restart falls back to the normal idle sweep.
+     * Defaults: debounceMs 45_000, maxConcurrent 2, cooldownMs 300_000.
+     */
+    fastFinalize?: {
+        enabled?: boolean;
+        /** Delay from the first severe event to the finalize attempt. Default 45_000. */
+        debounceMs?: number;
+        /** Global cap on concurrently running fast finalizes. Default 2. */
+        maxConcurrent?: number;
+        /** Minimum spacing between finalize attempts per session. Default 300_000. */
+        cooldownMs?: number;
+    };
+    /**
+     * Fired after every successful session finalization (including
+     * re-finalizations), from all three finalize paths: POST /api/session/end,
+     * the idle sweeper, and the severity-triggered fast finalizer. Embedders
+     * (e.g. crumbtrail-cloud) use it to learn about finalization in-process
+     * instead of polling. Must be fast and non-blocking — it runs on the
+     * finalize path. A throwing hook is swallowed and logged; it never fails
+     * the finalize or suppresses AI-diagnosis scheduling.
+     */
+    onSessionFinalized?: (sessionId: string, info: {
+        refinalized: boolean;
+    }) => void;
+    /**
+     * Test-only seam: overrides how the client's evidence sources are constructed
+     * for the inner /api/solve-context adapter phase (sessionless Mode A +
+     * blended). Production leaves this unset; gatherAdapterEvidence then builds
+     * them from env via evidenceSourcesFromEnv().
+     */
+    evidenceSourcesFactory?: () => EvidenceSource[];
+}
+declare function createServer(config: ServerConfig): http.Server;
+
+type CausalConfidence = "high" | "medium" | "low";
+
+interface LlmBundleFullStackEventRef {
+    t: number;
+    iso?: string;
+    offsetMs?: number;
+    kind?: string;
+}
+interface LlmBundleFrontendRequestEvidenceSummary {
+    ref?: LlmBundleFullStackEventRef;
+    requestId?: string;
+    sessionId?: string;
+    method?: string;
+    url?: string;
+    status?: number;
+    durationMs?: number;
+    error?: {
+        message?: string;
+        transport?: string;
+    };
+}
+interface LlmBundleBackendRequestEvidenceSummary {
+    requestId?: string;
+    sessionId?: string;
+    correlation?: {
+        status?: string;
+        sessionIdSource?: string;
+        requestIdSource?: string;
+    };
+    start?: LlmBundleFullStackEventRef;
+    end?: LlmBundleFullStackEventRef;
+    errorRef?: LlmBundleFullStackEventRef;
+    method?: string;
+    url?: string;
+    pathname?: string;
+    route?: string;
+    statusCode?: number;
+    durationMs?: number;
+    error?: {
+        name?: string;
+        code?: string;
+        message?: string;
+        statusCode?: number;
+    };
+}
+/**
+ * Redaction-aware summary of one `k:'db.diff'` event (a row that changed during a request),
+ * correlated to the request via `requestId`. CP5 DB diffing. Sensitive columns were dropped in the
+ * shim; bundle build re-runs the redaction policy as defense-in-depth.
+ */
+interface LlmBundleDbDiff {
+    t: number;
+    iso?: string;
+    offsetMs?: number;
+    engine: DbEngine;
+    op: "insert" | "update" | "delete";
+    table: string;
+    pk: Record<string, unknown> | null;
+    after?: Record<string, unknown>;
+    before?: Record<string, unknown>;
+    /**
+     * Only set on an image-less statement-level fallback event (`pk: null`, no `after`/`before`)
+     * where per-row images were unobtainable — records how many rows the statement changed so the
+     * write stays visible to differencing.
+     */
+    rowCount?: number;
+    requestId?: string;
+}
+interface LlmBundleDbRead {
+    t: number;
+    iso?: string;
+    offsetMs?: number;
+    engine: DbEngine;
+    table: string;
+    pk: Record<string, unknown> | null;
+    row: Record<string, unknown>;
+    requestId?: string;
+}
+interface LlmBundleDbActivity {
+    t: number;
+    iso?: string;
+    offsetMs?: number;
+    evidenceType: "otel_db_activity_statements_not_row_diffs";
+    system?: string;
+    operation?: string;
+    statement?: string;
+    spanName?: string;
+    serviceName?: string;
+    requestId?: string;
+    upgradeHint: string;
+}
+
+declare const CANDIDATE_SCHEMA_VERSION: 1;
+interface EvidenceCandidate {
+    schemaVersion: typeof CANDIDATE_SCHEMA_VERSION;
+    id: string;
+    detector: string;
+    title: string;
+    severity: "critical" | "high" | "medium" | "low";
+    score: number;
+    confidence: "high" | "medium" | "low";
+    anchor: {
+        t: number;
+        offsetMs?: number;
+        route?: string;
+        elementLabel?: string;
+        requestId?: string;
+        method?: string;
+        url?: string;
+        status?: number;
+        errorCode?: string;
+        message?: string;
+        source?: string;
+        target?: TargetDescriptor;
+    };
+    /** Causal role assigned by the confidence-gated re-rank (CP3). Additive/optional. */
+    causalRole?: "root" | "symptom" | "isolated";
+    /** For a symptom, the candidate id of its attributed root cause. */
+    rootCauseId?: string;
+    /** For a root, the sorted candidate ids of the symptoms attributed to it. */
+    causes?: string[];
+    /** Weakest edge confidence along the causal path from root to this symptom. */
+    attributionConfidence?: CausalConfidence;
+    evidenceWindow: {
+        start: number;
+        end: number;
+        windowId: string;
+    };
+}
+
+declare const DISTINCT_BUGS_SCHEMA_VERSION: 1;
+type DistinctBugSeverity = EvidenceCandidate["severity"];
+/**
+ * A reference back to one ranked {@link EvidenceCandidate} that contributed to a distinct bug.
+ * Carries only already-redacted, candidate-derived fields so the grouped view re-exposes nothing.
+ */
+interface DistinctBugEvidenceRef {
+    candidateId: string;
+    detector: string;
+    t: number;
+    offsetMs?: number;
+    requestId?: string;
+    method?: string;
+    status?: number;
+    route?: string;
+    target?: TargetDescriptor;
+    message?: string;
+}
+/**
+ * One DISTINCT, labeled bug a single session hit, grouped deterministically from the ranked
+ * evidence candidates. Front-end and back-end evidence are split so the bug carries its correlated
+ * window; correlated requests/traces share one bug via {@link DistinctBug.requestIds}.
+ */
+interface DistinctBug {
+    schemaVersion: typeof DISTINCT_BUGS_SCHEMA_VERSION;
+    bugId: string;
+    title: string;
+    severity: DistinctBugSeverity;
+    firstSeen: number;
+    lastSeen: number;
+    window: {
+        start: number;
+        end: number;
+    };
+    requestIds: string[];
+    representative: {
+        title: string;
+        detector: string;
+        severity: DistinctBugSeverity;
+        message?: string;
+        route?: string;
+        method?: string;
+        status?: number;
+        target?: TargetDescriptor;
+        requestId?: string;
+    };
+    frontendEvidence: DistinctBugEvidenceRef[];
+    backendEvidence: DistinctBugEvidenceRef[];
+    dbDiffs?: DistinctBugEvidenceRef[];
+    candidateIds: string[];
+}
+interface DistinctBugRecurrenceInput {
+    bug: DistinctBug;
+    session: {
+        sessionId: string;
+        dir?: string;
+        app?: string;
+        tenant?: string;
+        release?: string;
+        build?: string;
+        start?: number;
+    };
+}
+interface DistinctBugRecurrenceOccurrence {
+    sessionId: string;
+    bugId: string;
+    title: string;
+    severity: DistinctBugSeverity;
+    firstSeen: number;
+    lastSeen: number;
+    app?: string;
+    tenant?: string;
+    release?: string;
+    build?: string;
+    dir?: string;
+}
+interface DistinctBugRecurrence {
+    signature: string;
+    title: string;
+    severity: DistinctBugSeverity;
+    first_seen: number;
+    last_seen: number;
+    session_count: number;
+    release_span?: {
+        first: string;
+        last: string;
+        label: string;
+    };
+    apps: string[];
+    tenants: string[];
+    occurrences: DistinctBugRecurrenceOccurrence[];
+}
+/**
+ * Groups the ranked candidates into DISTINCT bugs deterministically.
+ *
+ * Grouping key heuristics (deterministic, order-independent):
+ *  - Candidates sharing a correlated `anchor.requestId` (Crumbtrail request id or W3C trace id)
+ *    collapse into ONE bug, so the front-end signal and its back-end span/log land together.
+ *  - Remaining candidates cluster by `(detector + normalized message/error signature + component
+ *    signature)` within a {@link CLUSTER_WINDOW_MS} time window. Identical signatures far apart in
+ *    time become separate bugs (disambiguated with a stable `#n` suffix so their ids never collide).
+ *
+ * The `bugId` is `bug_<hash>` where the hash is a stable FNV-1a digest of the dedup key — identical
+ * input always yields identical ids and ordering. Bugs are sorted by severity desc, then firstSeen
+ * asc, then bugId asc.
+ */
+declare function groupDistinctBugs(candidates: EvidenceCandidate[]): DistinctBug[];
+declare function buildDistinctBugSignature(bug: Pick<DistinctBug, "title" | "representative">): string;
+declare function groupDistinctBugRecurrences(inputs: DistinctBugRecurrenceInput[]): DistinctBugRecurrence[];
+
+interface AppendEventsOptions {
+    maxEventBytes?: number;
+}
+interface AppendEventsResult {
+    accepted: number;
+    dropped: number;
+    truncated: boolean;
+    bytesWritten: number;
+}
+interface ArtifactStat {
+    bytes: number;
+    isDir: boolean;
+}
+interface ResolveSessionScope {
+    tenant?: string;
+    app?: string;
+    date?: string;
+}
+/**
+ * Storage boundary for a single session's on-disk artifacts. Every filesystem
+ * write/read primitive that the node package performs against a session
+ * directory flows through this seam so the layout can later move behind an
+ * alternate backend (e.g. R2) without touching call sites.
+ */
+interface SessionStore {
+    createSessionDir(sessionId: string): string;
+    appendEvents(sessionDir: string, events: BugEvent[], opts?: AppendEventsOptions): AppendEventsResult;
+    writeArtifact(sessionDir: string, name: string, data: string | Buffer): void;
+    writeBlob(sessionDir: string, name: string, data: Buffer): void;
+    writeSessionArtifact(sessionDir: string, name: string, data: string | Buffer): void;
+    readArtifact(sessionDir: string, name: string): Buffer | undefined;
+    statArtifact(sessionDir: string, name: string): ArtifactStat | undefined;
+    listSessions(outputDir: string): Array<{
+        id: string;
+        dir: string;
+    }>;
+    listArtifacts(sessionDir: string): string[];
+    /**
+     * Atomically relocate `sessionDir` to `targetDir` (staging -> finalized partition).
+     * This is the load-bearing FS-only "atomic rename" semantic the R2 adapter will have
+     * to emulate. Path/containment/symlink policy is enforced by the caller before and
+     * after the move (see SessionManager.moveSessionToV2Partition); this primitive owns
+     * only the atomic move itself.
+     */
+    moveToPartition(sessionDir: string, targetDir: string): string;
+    resolveSessionDir(idOrDir: string, outputDir?: string, scope?: ResolveSessionScope): string;
+    /**
+     * Tenant-scoped lookup with the cloud isolation contract: returns the session dir only
+     * when it exists inside {sessionsDir}/{tenant}/{app}/{YYYY-MM-DD}/{sessionId}, else
+     * undefined (never a fallback path, never a cross-tenant hit). Backs cloud's findSessionDir.
+     */
+    resolveScopedSessionDir(sessionsDir: string, tenant: string, app: string, sessionId: string): string | undefined;
+    deleteSessionDir(sessionDir: string): void;
+}
+declare class FilesystemSessionStore implements SessionStore {
+    createSessionDir(sessionId: string): string;
+    appendEvents(sessionDir: string, events: BugEvent[], opts?: AppendEventsOptions): AppendEventsResult;
+    writeArtifact(sessionDir: string, name: string, data: string | Buffer): void;
+    writeBlob(sessionDir: string, name: string, data: Buffer): void;
+    writeSessionArtifact(sessionDir: string, name: string, data: string | Buffer): void;
+    readArtifact(sessionDir: string, name: string): Buffer | undefined;
+    statArtifact(sessionDir: string, name: string): ArtifactStat | undefined;
+    listSessions(outputDir: string): Array<{
+        id: string;
+        dir: string;
+    }>;
+    listArtifacts(sessionDir: string): string[];
+    moveToPartition(sessionDir: string, targetDir: string): string;
+    resolveSessionDir(idOrDir: string, outputDir?: string, scope?: ResolveSessionScope): string;
+    resolveScopedSessionDir(sessionsDir: string, tenant: string, app: string, sessionId: string): string | undefined;
+    deleteSessionDir(sessionDir: string): void;
+}
+declare const defaultSessionStore: SessionStore;
+
+declare const DEFAULT_SWEEP_IDLE_MS: number;
+declare const DEFAULT_SWEEP_INTERVAL_MS: number;
+declare const DEFAULT_SWEEP_CHECKPOINT_MS: number;
+interface SessionSweepOptions {
+    sessions: SessionManager;
+    outputDir: string;
+    /** Inactivity threshold before an un-finalized session is swept. */
+    idleMs?: number;
+    /**
+     * Checkpoint threshold for sessions that never go idle: an un-finalized
+     * session older than this is finalized even while active, and an active
+     * finalized session with late events is re-finalized once per window.
+     */
+    checkpointMs?: number;
+    /** Upper bound on finalizations (incl. re-finalizations) per sweep. */
+    maxPerSweep?: number;
+    /** Called after each successful finalize (e.g. to schedule AI diagnosis). */
+    onFinalized?: (sessionId: string, refinalized: boolean) => void;
+    /** Clock seam for tests. */
+    now?: () => number;
+}
+interface SessionSweepResult {
+    scanned: number;
+    finalized: number;
+    refinalized: number;
+    failed: number;
+    /** Candidates left alone because they saw activity within idleMs. */
+    active: number;
+}
+/**
+ * One sweep pass: finalize every idle un-finalized session, and re-finalize
+ * every finalized session that received events after its last finalization.
+ * Serial by design. Returns counts for logging; never throws.
+ */
+declare function sweepIdleSessions(options: SessionSweepOptions): Promise<SessionSweepResult>;
+interface SessionSweeperHandle {
+    stop(): void;
+    /** Run one sweep immediately (test seam; also used by the interval). */
+    sweepNow(): Promise<SessionSweepResult>;
+}
+/**
+ * Start the periodic sweeper. The timer is unref'd so it never keeps a
+ * process alive, and ticks never overlap (a long postProcess simply delays
+ * the next pass).
+ */
+declare function startSessionSweeper(options: SessionSweepOptions & {
+    intervalMs?: number;
+    /** Called with each sweep's counts whenever a sweep did any work. */
+    onSweep?: (result: SessionSweepResult) => void;
+}): SessionSweeperHandle;
+
+interface BugReport {
+    bugId: string;
+    sessionId: string;
+    flaggedAt: number;
+    windowMs: number;
+    note?: string;
+    voiceNote?: string;
+    url: string;
+    userAgent: string;
+    tags?: string[];
+    status?: "open" | "resolved";
+    summary: {
+        errorCount: number;
+        failedRequestCount: number;
+        eventCount: number;
+        eventKinds: Record<string, number>;
+        durationMs: number;
+    };
+}
+interface BugQueueConfig {
+    bugsDir: string;
+    whisperModel?: string;
+}
+interface LlmBugContext {
+    v: 1;
+    id: string;
+    sid: string;
+    ts: number;
+    w: number;
+    u: string;
+    n?: string;
+    g?: string[];
+    s: {
+        e: number;
+        f: number;
+        c: number;
+        d: number;
+        k: Record<string, number>;
+    };
+    err?: Array<{
+        t: number;
+        m: string;
+    }>;
+    req?: Array<{
+        t: number;
+        m: string;
+        u: string;
+        s: number;
+    }>;
+    nav?: Array<{
+        t: number;
+        to: string;
+    }>;
+}
+declare class BugQueueManager {
+    private bugsDir;
+    private whisperModel?;
+    constructor(config: BugQueueConfig);
+    create(report: BugReport, events: BugEvent[]): Promise<void>;
+    writeVoice(bugId: string, data: Buffer): Promise<boolean>;
+    list(filters?: {
+        after?: number;
+        before?: number;
+        status?: string;
+        tags?: string[];
+    }): BugReport[];
+    get(bugId: string): BugReport | null;
+    getBugDir(bugId: string): string;
+    resolve(bugId: string): void;
+    getLlmContext(bugId: string): LlmBugContext | null;
+    private resolveBugDir;
+    private resolveBugStagingDir;
+    private assertBugDirAvailable;
+    private assertSafeBugDir;
+    private writeLlmContext;
+    private writeLlmContextForDir;
+}
+
+/**
+ * Outcome of an on-demand reproduction attempt against a symptom. Reserved
+ * for the injected `Reproducer` seam consumed by `solveContext` when
+ * historical evidence is thin — see `docs/integrations/reproduction.md`.
+ */
+interface ReproductionResult {
+    attempted: boolean;
+    /** Where a fresh session was recorded, if any. */
+    sessionDir?: string;
+    /** Fresh evidence gathered (empty if none). */
+    evidence: EvidenceItem[];
+    /** Usually empty; reserved. */
+    intent: IntentSignal[];
+    /** Human/agent-readable outcome. */
+    note: string;
+}
+interface Reproducer {
+    reproduce(symptom: Symptom): Promise<ReproductionResult>;
+}
+
+/**
+ * Parallel adapter fan-out. Queries every configured {@link EvidenceSource} at
+ * once, bounds each by a per-source timeout, redacts every result at the
+ * boundary, and enforces a global byte cap across all sources. It NEVER throws:
+ * a failed or slow source becomes an {@link EvidenceGap} ("sentry: timeout after
+ * 10s"), because evidence is advisory and "inconclusive" is a valid outcome.
+ */
+/** Per-source timeout when neither the query nor options specify one. */
+declare const DEFAULT_SOURCE_TIMEOUT_MS = 10000;
+/** Global cap on normalized (redacted) evidence bytes across all sources. */
+declare const DEFAULT_MAX_TOTAL_BYTES: number;
+interface AdapterSourceStats {
+    provider: string;
+    /**
+     * Health signal for this source. INVARIANT: `ok` is false iff the source
+     * could not deliver its PRIMARY evidence — a total failure/timeout that
+     * returned zero items — regardless of whether the adapter threw or
+     * self-degraded internally. A source that returned any items (even partial,
+     * with an enrichment/secondary gap) stays `ok: true`. The framework is the
+     * single source of truth: it derives `ok` from the throw path OR a
+     * `kind: "source-unavailable"` gap on a zero-item result (see below), never
+     * from gap `reason` text.
+     */
+    ok: boolean;
+    /** Items the source reported fetching (0 on failure). */
+    fetched: number;
+    /** Items actually included after the global byte cap. */
+    returned: number;
+    /** True if the source's own maxItems OR the global byte cap dropped items. */
+    truncated: boolean;
+    /** Framework-measured wall time for this source's fetch. */
+    latencyMs: number;
+    /** Bytes of this source's included normalized items. */
+    bytes: number;
+    /** Sanitized failure/timeout reason when `ok` is false. */
+    error?: string;
+}
+interface AdapterEvidence {
+    items: EvidenceItem[];
+    gaps: EvidenceGap[];
+    stats: AdapterSourceStats[];
+}
+interface FetchAdapterEvidenceOptions {
+    /** Per-source timeout override (else query.limits.timeoutMs, else default). */
+    timeoutMs?: number;
+    /** Global byte cap across sources. Default 512 KB. */
+    maxTotalBytes?: number;
+    /** Clock hook (tests). Default Date.now. */
+    now?: () => number;
+}
+/**
+ * Fan out `query` to every source in parallel, degrade failures to gaps, redact
+ * at the boundary, and cap total normalized bytes. Deterministic: outcomes are
+ * folded in source order, so the byte cap trims from a stable point.
+ */
+declare function fetchAdapterEvidence(sources: EvidenceSource[], query: EvidenceQuery, options?: FetchAdapterEvidenceOptions): Promise<AdapterEvidence>;
+
+declare function redactEvidenceItem(item: EvidenceItem, index?: number): EvidenceItem;
+declare function redactEvidenceGap(gap: EvidenceGap, index?: number): EvidenceGap;
+/**
+ * Redact a whole adapter result. Returns a new result (items + gaps redacted);
+ * `stats` and `schemaVersion` pass through untouched.
+ */
+declare function redactSourceResult(result: EvidenceSourceResult): EvidenceSourceResult;
+
+/**
+ * Sentry evidence adapter — the reference implementation every other adapter
+ * (CloudWatch, Splunk, Datadog, PostHog, Cloudflare) copies.
+ *
+ * It is a query-at-incident-time pull: given a located incident window and the
+ * correlation keys known for it, ask Sentry's REST API for the issues/events in
+ * that window and normalize each into the neutral `evidence.v1` contract. It is
+ * zero-copy — nothing Sentry returns is persisted; only the derived bundle is.
+ *
+ * Load-bearing patterns for CP4–CP7 to mirror:
+ * - **Primary-first, enrichment-best-effort**: neutral items are built from the
+ *   list/query call (the PRIMARY evidence — `brief`, `ref`, `whenObserved`) and
+ *   emitted regardless of any secondary enrichment. Enrichment (here: per-issue
+ *   stack heads) fans out with capped concurrency inside a sub-budget carved
+ *   from `limits.timeoutMs`; if it is slow, fails, or the abort signal fires,
+ *   the primary items still ship with a less-enriched field (`after: null`) —
+ *   never nothing. This keeps a timed-out source degrading to "fewer/less-rich
+ *   items + a gap," never "zero items."
+ * - **Injectable transport**: the constructor takes `fetchImpl?: typeof fetch`.
+ *   Production uses global `fetch`; contract tests inject a stub that replays
+ *   recorded fixtures, so there is zero network in CI.
+ * - **Descriptor-keyed query construction**: the search query is built strictly
+ *   from `descriptor.joinKeys` ∩ the keys present in `EvidenceQuery.keys`, and a
+ *   requested key the adapter cannot use becomes an honest {@link EvidenceGap}
+ *   rather than a silent drop.
+ * - **Boundaries**: never throws out of `fetchEvidence` in a way the framework
+ *   can't turn into a gap; honors `limits.maxItems`/`maxBytes`; no pagination
+ *   walk beyond `maxItems`; every request carries `CRUMBTRAIL_USER_AGENT`; the
+ *   auth token lives only in the Authorization header, never in a message.
+ * - **Redaction stays at the framework boundary** (`redact.ts` /
+ *   `fetchAdapterEvidence`); this file only populates the fields that boundary
+ *   scrubs (`brief`, `after`, `ref.url`).
+ */
+/** Env var carrying the Sentry auth token (Bearer). Required. */
+declare const SENTRY_AUTH_TOKEN_ENV = "CRUMBTRAIL_SENTRY_AUTH_TOKEN";
+/** Env var carrying the Sentry organization slug. Required. */
+declare const SENTRY_ORG_ENV = "CRUMBTRAIL_SENTRY_ORG";
+/** Env var overriding the API host (self-hosted Sentry). Optional. */
+declare const SENTRY_HOST_ENV = "CRUMBTRAIL_SENTRY_HOST";
+/** Default SaaS host when {@link SENTRY_HOST_ENV} is unset. */
+declare const SENTRY_DEFAULT_HOST = "https://sentry.io";
+/** Presence of these two ⇒ the provider is configured (mirrors ticket clients). */
+declare const SENTRY_AUTH_FIELDS: string[];
+declare const SENTRY_DESCRIPTOR: EvidenceSourceDescriptor;
+interface SentrySourceConfig {
+    authToken: string;
+    org: string;
+    /** API host, no trailing slash. Defaults to {@link SENTRY_DEFAULT_HOST}. */
+    host?: string;
+    /** Injectable transport. Defaults to global `fetch`. Tests pass a stub. */
+    fetchImpl?: typeof fetch;
+}
+interface SentryQueryPlan {
+    /** Sentry search query string (may be empty ⇒ time-window only). */
+    search: string;
+    /** Join keys actually used to narrow beyond the time window, best-first. */
+    usedKeys: EvidenceJoinKey[];
+    /** Honest gaps: a requested key Sentry cannot filter by. */
+    gaps: EvidenceGap[];
+}
+/**
+ * Build the Sentry search query from `descriptor.joinKeys` ∩ present keys.
+ * Precedence: a `trace:{traceId}` token when a trace is present (tightest), else
+ * `url:` / `release:` / `user.email:` tokens for whichever of those keys is
+ * present. Any requested key Sentry does NOT support (requestId, sessionId,
+ * service, and — when no trace is present — nothing to pin on) yields a gap so
+ * the bundle states plainly what filtered the result.
+ */
+declare function buildSentryQuery(query: EvidenceQuery): SentryQueryPlan;
+/** Minimal shape of the Sentry issues-list rows we consume. */
+interface SentryIssue {
+    id: string;
+    title?: string;
+    culprit?: string;
+    permalink?: string;
+    lastSeen?: string;
+    firstSeen?: string;
+    metadata?: {
+        value?: string;
+        type?: string;
+    };
+}
+/** Minimal shape of a Sentry event (from `/issues/{id}/events/latest/`). */
+interface SentryEvent {
+    id?: string;
+    dateCreated?: string;
+    entries?: Array<{
+        type?: string;
+        data?: unknown;
+    }>;
+}
+/** Sentry issue + its latest event → neutral evidence.v1 item. Pure. */
+declare function normalizeSentryIssue(issue: SentryIssue, event?: SentryEvent): EvidenceItem;
+declare class SentryEvidenceSource implements EvidenceSource {
+    readonly descriptor: EvidenceSourceDescriptor;
+    private readonly authToken;
+    private readonly org;
+    private readonly host;
+    private readonly fetchImpl;
+    constructor(config: SentrySourceConfig);
+    private headers;
+    private getJson;
+    /** Cheap authenticated no-op: GET the org endpoint. */
+    health(signal?: AbortSignal): Promise<SourceHealth>;
+    /** GET the latest event for one issue (for its stack head). A per-issue
+     *  enrichment failure is non-fatal: we return undefined and the item is still
+     *  emitted with `after: null` rather than sinking the whole fetch. Single
+     *  attempt on purpose — this runs once per issue, so retrying it would let the
+     *  best-effort enrichment blow the per-source timeout budget; the primary
+     *  issues query keeps the bounded retry. */
+    private fetchLatestEvent;
+    /**
+     * OPTIONAL stack-head enrichment — the resilient pattern CP4–CP7 mirror.
+     *
+     * Fans out `/events/latest/` calls with capped concurrency, bounded by BOTH
+     * the caller's abort signal AND a sub-budget carved from the per-source
+     * timeout (`ENRICH_BUDGET_FRACTION` of `limits.timeoutMs`). A slow, failed, or
+     * aborted event fetch simply leaves that issue's event `undefined` (→
+     * `after: null`); it never blocks or drops the primary issues-list evidence.
+     * Returns the per-issue events (index-aligned to `issues`) plus `incomplete`,
+     * set when the signal fired or the sub-budget was exhausted before every
+     * enrichment finished.
+     */
+    private enrichStackHeads;
+    fetchEvidence(query: EvidenceQuery, signal?: AbortSignal): Promise<EvidenceSourceResult>;
+}
+/** Registry entry: build a Sentry source from env when its auth fields are set. */
+declare const sentryEvidenceProvider: EvidenceSourceProvider;
+
+/**
+ * CloudWatch Logs Insights evidence adapter — the second adapter, built to the
+ * Sentry reference shape (`sentry.ts`). Query-at-incident-time pull: given a
+ * located incident window and the correlation keys known for it, run a Logs
+ * Insights query over the configured log group(s) and normalize each matching
+ * log line into the neutral `evidence.v1` contract. Zero-copy — nothing AWS
+ * returns is persisted; only the derived bundle is.
+ *
+ * Load-bearing patterns mirrored from the Sentry reference:
+ * - **Injectable transport**: constructor takes `fetchImpl?: typeof fetch`
+ *   defaulting to global `fetch`; contract tests inject a fixture-routing stub so
+ *   there is zero network in CI.
+ * - **Resilience / self-limiting poll budget**: Logs Insights is async —
+ *   `StartQuery` then poll `GetQueryResults`. The polling loop is the analog of
+ *   Sentry's best-effort enrichment: it self-limits to a sub-budget carved from
+ *   `limits.timeoutMs` (`POLL_BUDGET_FRACTION`) so the adapter resolves BEFORE
+ *   the framework's per-source race fires, and it keeps the newest partial result
+ *   snapshot. A query that out-runs the budget degrades to the rows that
+ *   completed + an honest gap ("cloudwatch: query did not complete within Ns"),
+ *   never "no items."
+ * - **Descriptor-keyed query construction**: the `filter` term is built strictly
+ *   from `descriptor.joinKeys` ∩ present keys; a requested key CloudWatch cannot
+ *   use becomes an honest {@link EvidenceGap} rather than a silent drop.
+ * - **Boundaries**: honors `limits.maxItems`/`maxBytes`/`timeoutMs`; no
+ *   pagination walk beyond `maxItems`; every request is SigV4-signed and carries
+ *   `CRUMBTRAIL_USER_AGENT`; credentials live only in the signing path, never in a
+ *   gap, stat, thrown message, or log.
+ * - **Redaction stays at the framework boundary** (`redact.ts`); this file only
+ *   populates the fields that boundary scrubs (`brief`, `after`, `ref.url`).
+ */
+/** Env var carrying the AWS access key id. Required. */
+declare const CLOUDWATCH_ACCESS_KEY_ID_ENV = "CRUMBTRAIL_CLOUDWATCH_ACCESS_KEY_ID";
+/** Env var carrying the AWS secret access key. Required. */
+declare const CLOUDWATCH_SECRET_ACCESS_KEY_ENV = "CRUMBTRAIL_CLOUDWATCH_SECRET_ACCESS_KEY";
+/** Env var carrying the AWS region, e.g. "us-east-1". Required. */
+declare const CLOUDWATCH_REGION_ENV = "CRUMBTRAIL_CLOUDWATCH_REGION";
+/** Env var carrying a comma-separated list of log group names. Required. */
+declare const CLOUDWATCH_LOG_GROUPS_ENV = "CRUMBTRAIL_CLOUDWATCH_LOG_GROUPS";
+/** Env var carrying an STS session token for temporary/role creds. Optional. */
+declare const CLOUDWATCH_SESSION_TOKEN_ENV = "CRUMBTRAIL_CLOUDWATCH_SESSION_TOKEN";
+/** Env var overriding the Logs endpoint host (govcloud/localstack). Optional. */
+declare const CLOUDWATCH_ENDPOINT_ENV = "CRUMBTRAIL_CLOUDWATCH_ENDPOINT";
+/** Presence of these four ⇒ the provider is configured (mirrors ticket clients). */
+declare const CLOUDWATCH_AUTH_FIELDS: string[];
+declare const CLOUDWATCH_DESCRIPTOR: EvidenceSourceDescriptor;
+interface CloudWatchSourceConfig {
+    accessKeyId: string;
+    secretAccessKey: string;
+    region: string;
+    /** Log group names to query, one Logs Insights query each. */
+    logGroups: string[];
+    /** STS session token for temporary/role credentials. Optional. */
+    sessionToken?: string;
+    /** Logs endpoint host override (no trailing slash). Defaults to the regional
+     *  `https://logs.{region}.amazonaws.com`. */
+    endpoint?: string;
+    /** Injectable transport. Defaults to global `fetch`. Tests pass a stub. */
+    fetchImpl?: typeof fetch;
+    /** Poll interval override (ms) for the GetQueryResults loop. Tests shrink it. */
+    pollIntervalMs?: number;
+}
+interface CloudWatchQueryPlan {
+    /** The Logs Insights query string (fields/filter/sort/limit). */
+    queryString: string;
+    /** Join keys actually used to narrow beyond the time window, best-first. */
+    usedKeys: EvidenceJoinKey[];
+    /** Honest gaps: a requested key CloudWatch cannot filter by. */
+    gaps: EvidenceGap[];
+}
+/**
+ * Build the Logs Insights query from `descriptor.joinKeys` ∩ present keys.
+ * Precedence: a `filter @message like "<id>"` term when a requestId/traceId is
+ * present (the tightest correlation Logs Insights offers on unstructured logs),
+ * else a time-window-only scan (the window is expressed via StartQuery's
+ * start/end, not the query string). Any requested key CloudWatch does NOT support
+ * (sessionId, release, url, user) yields a gap so the bundle states plainly what
+ * filtered the result.
+ */
+declare function buildCloudWatchQuery(query: EvidenceQuery): CloudWatchQueryPlan;
+/** One Logs Insights result row: a list of `{ field, value }` cells. */
+type CloudWatchResultRow = Array<{
+    field?: string;
+    value?: string;
+}>;
+/**
+ * CloudWatch Logs Insights console deep link for a log group in a region, so a
+ * human can open the source. The console double-encodes path separators
+ * (`/` → `$252F`). This links to the log group; a token-bearing URL would be
+ * scrubbed at the redaction boundary anyway (there is none here).
+ */
+declare function cloudWatchDeepLink(region: string, logGroup: string): string;
+/** One Logs Insights row → neutral evidence.v1 item. Pure. */
+declare function normalizeCloudWatchRow(row: CloudWatchResultRow, region: string, logGroup: string): EvidenceItem;
+declare class CloudWatchEvidenceSource implements EvidenceSource {
+    readonly descriptor: EvidenceSourceDescriptor;
+    private readonly accessKeyId;
+    private readonly secretAccessKey;
+    private readonly region;
+    private readonly logGroups;
+    private readonly sessionToken?;
+    private readonly endpoint;
+    private readonly fetchImpl;
+    private readonly pollIntervalMs;
+    constructor(config: CloudWatchSourceConfig);
+    /**
+     * One signed POST to the Logs JSON API. `action` is the short target name
+     * (e.g. "StartQuery"). The SigV4 signature and the (non-secret) User-Agent are
+     * the only auth material on the wire; the secret key never leaves the signer.
+     */
+    private post;
+    private startQuery;
+    private getQueryResults;
+    /** Cheap authenticated no-op: DescribeLogGroups with limit 1. */
+    health(signal?: AbortSignal): Promise<SourceHealth>;
+    /**
+     * Run one log group's Logs Insights query end-to-end: StartQuery, then poll
+     * GetQueryResults until Complete, a terminal non-complete status, or the
+     * shared deadline/abort fires. Keeps the newest partial `results` snapshot so
+     * a query that out-runs the budget still yields the rows that had completed —
+     * never empty. A group whose query throws (bad creds, missing group) degrades
+     * to `error` on the outcome rather than sinking the other groups' rows.
+     */
+    private runGroupQuery;
+    fetchEvidence(query: EvidenceQuery, signal?: AbortSignal): Promise<EvidenceSourceResult>;
+}
+/** Registry entry: build a CloudWatch source from env when its auth fields are set. */
+declare const cloudWatchEvidenceProvider: EvidenceSourceProvider;
+
+interface SigV4Input {
+    method: string;
+    /** Absolute request URL (host + path + optional query). */
+    url: string;
+    region: string;
+    /** AWS service name, e.g. "logs". */
+    service: string;
+    accessKeyId: string;
+    secretAccessKey: string;
+    /** Temporary-credential session token (STS/role). Signed + echoed when set. */
+    sessionToken?: string;
+    /** Request body (already serialized). Hashed into the canonical request. */
+    body: string;
+    /** Non-auth headers to sign (e.g. content-type, x-amz-target). */
+    headers: Record<string, string>;
+    /** Signing instant. Injectable for deterministic tests. Default `new Date()`. */
+    now?: Date;
+}
+interface SignedHeaders {
+    [name: string]: string;
+}
+/**
+ * Sign `input` and return the request headers to send (the caller's headers plus
+ * `X-Amz-Date`, `Authorization`, and `X-Amz-Security-Token` when a session token
+ * is present). Pure and synchronous.
+ */
+declare function signSigV4(input: SigV4Input): SignedHeaders;
+
+/**
+ * Splunk evidence adapter — built to the Sentry reference shape (`sentry.ts`) and
+ * the CloudWatch async-poll shape (`cloudwatch.ts`). Query-at-incident-time pull:
+ * given a located incident window and the correlation keys known for it, run a
+ * bounded SPL search over the configured index(es) and normalize each matching
+ * event into the neutral `evidence.v1` contract. Zero-copy — nothing Splunk
+ * returns is persisted; only the derived bundle is.
+ *
+ * Load-bearing patterns mirrored from the references:
+ * - **Injectable transport**: constructor takes `fetchImpl?: typeof fetch`
+ *   defaulting to global `fetch`; contract tests inject a fixture-routing stub so
+ *   there is zero network in CI.
+ * - **Resilience / self-limiting search budget**: a Splunk search is async —
+ *   `POST .../jobs` dispatches a job, then we poll `.../results_preview`. The poll
+ *   loop is the analog of CloudWatch's poll: it self-limits to a sub-budget carved
+ *   from `limits.timeoutMs` (`POLL_BUDGET_FRACTION`) so the adapter resolves BEFORE
+ *   the framework's per-source race fires, and it keeps the newest partial preview
+ *   snapshot. A search that out-runs the budget degrades to the rows Splunk had
+ *   previewed + an honest gap ("splunk: search did not complete within Ns"),
+ *   never "no items."
+ * - **Descriptor-keyed query construction**: the SPL terms are built strictly from
+ *   `descriptor.joinKeys` ∩ present keys; a requested key Splunk cannot use becomes
+ *   an honest {@link EvidenceGap} rather than a silent drop. Every declared join
+ *   key is genuinely applied (traceId/requestId as a term, service as a field
+ *   filter, time as earliest/latest) — no silent no-op.
+ * - **Boundaries**: honors `limits.maxItems`/`maxBytes`/`timeoutMs`; the `count`
+ *   arg caps results server-side so there is no pagination walk beyond `maxItems`;
+ *   every request carries `CRUMBTRAIL_USER_AGENT`; the token lives only in the
+ *   Authorization header, never in a gap, stat, thrown message, or log.
+ * - **Redaction stays at the framework boundary** (`redact.ts`); this file only
+ *   populates the fields that boundary scrubs (`brief`, `after`, `ref.url`).
+ */
+/** Env var carrying the Splunk search head base URL (incl. mgmt port, e.g.
+ *  `https://splunk.example.com:8089`). Required. */
+declare const SPLUNK_HOST_ENV = "CRUMBTRAIL_SPLUNK_HOST";
+/** Env var carrying the Splunk authentication (JWT) token. Required. */
+declare const SPLUNK_TOKEN_ENV = "CRUMBTRAIL_SPLUNK_TOKEN";
+/** Env var carrying a comma-separated list of allowed indexes. Required. */
+declare const SPLUNK_INDEX_ENV = "CRUMBTRAIL_SPLUNK_INDEX";
+/** Env var overriding the web UI base URL for deep links (e.g.
+ *  `https://splunk.example.com:8000`). Optional — derived from the host if unset. */
+declare const SPLUNK_WEB_URL_ENV = "CRUMBTRAIL_SPLUNK_WEB_URL";
+/** Presence of these three ⇒ the provider is configured (mirrors ticket clients). */
+declare const SPLUNK_AUTH_FIELDS: string[];
+declare const SPLUNK_DESCRIPTOR: EvidenceSourceDescriptor;
+interface SplunkSourceConfig {
+    /** Search head base URL (no trailing slash), typically the :8089 mgmt port. */
+    host: string;
+    /** Splunk authentication (JWT) token. */
+    token: string;
+    /** Allowed index names; the SPL scans these (OR-joined). */
+    indexes: string[];
+    /** Web UI base URL for deep links. Defaults to a best-effort host derivation. */
+    webUrl?: string;
+    /** Injectable transport. Defaults to global `fetch`. Tests pass a stub. */
+    fetchImpl?: typeof fetch;
+    /** Poll interval override (ms) for the results_preview loop. Tests shrink it. */
+    pollIntervalMs?: number;
+}
+interface SplunkQueryPlan {
+    /** The full SPL string (starts with `search`, incl. index + earliest/latest). */
+    spl: string;
+    /** Join keys actually used to narrow beyond the time window, best-first. */
+    usedKeys: EvidenceJoinKey[];
+    /** Honest gaps: a requested key Splunk cannot filter by. */
+    gaps: EvidenceGap[];
+}
+/**
+ * Build the SPL from `descriptor.joinKeys` ∩ present keys.
+ * Precedence: a bare quoted correlation-id term (traceId, else requestId) is the
+ * tightest filter over raw events; `service="<svc>"` is applied additively as a
+ * field filter; the time window is always expressed via `earliest`/`latest`. Any
+ * requested key Splunk does NOT support (sessionId, release, url, user) yields a
+ * gap so the bundle states plainly what filtered the result.
+ */
+declare function buildSplunkQuery(query: EvidenceQuery, indexes: string[]): SplunkQueryPlan;
+/** One Splunk search result row (the `results[]` entries in the JSON output). */
+interface SplunkResultRow {
+    _raw?: string;
+    _time?: string;
+    _cd?: string;
+    _bkt?: string;
+    index?: string;
+    sourcetype?: string;
+    [field: string]: unknown;
+}
+/**
+ * Derive a best-effort web UI base for deep links from the mgmt host: the mgmt
+ * port (8089) becomes the default web port (8000); otherwise the origin is used.
+ * A configured {@link SplunkSourceConfig.webUrl} always wins.
+ */
+declare function splunkWebBase(host: string, webUrl?: string): string;
+/**
+ * Splunk search-app deep link that lands on the SPL + time range the event came
+ * from — the practical "actual search where the log lives" link (better than a
+ * bare index link). The mgmt API host carries no UI, so we point at the web base.
+ */
+declare function splunkSearchDeepLink(webBase: string, spl: string, window: {
+    start: number;
+    end: number;
+}): string;
+/** One Splunk result row → neutral evidence.v1 item. Pure. */
+declare function normalizeSplunkRow(row: SplunkResultRow, webBase: string, spl: string, window: {
+    start: number;
+    end: number;
+}): EvidenceItem;
+declare class SplunkEvidenceSource implements EvidenceSource {
+    readonly descriptor: EvidenceSourceDescriptor;
+    private readonly host;
+    private readonly token;
+    private readonly indexes;
+    private readonly webBase;
+    private readonly fetchImpl;
+    private readonly pollIntervalMs;
+    constructor(config: SplunkSourceConfig);
+    private headers;
+    private getJson;
+    /** Dispatch a search job (form-encoded), returning its sid. */
+    private createJob;
+    /** Fetch the newest preview snapshot for a job (also final rows once done). */
+    private previewResults;
+    /** Cheap authenticated no-op: GET server info. */
+    health(signal?: AbortSignal): Promise<SourceHealth>;
+    fetchEvidence(query: EvidenceQuery, signal?: AbortSignal): Promise<EvidenceSourceResult>;
+}
+/** Registry entry: build a Splunk source from env when its auth fields are set. */
+declare const splunkEvidenceProvider: EvidenceSourceProvider;
+
+/**
+ * Datadog evidence adapter — built to the Sentry reference shape (`sentry.ts`).
+ * Query-at-incident-time pull: given a located incident window and the
+ * correlation keys known for it, ask Datadog's Logs Search v2 API (primary) and
+ * Spans Search v2 API (secondary) for matching records in that window, and
+ * normalize each into the neutral `evidence.v1` contract. Zero-copy — nothing
+ * Datadog returns is persisted; only the derived bundle is.
+ *
+ * Load-bearing patterns mirrored from the Sentry reference:
+ * - **Injectable transport**: constructor takes `fetchImpl?: typeof fetch`
+ *   defaulting to global `fetch`; contract tests inject a fixture-routing stub so
+ *   there is zero network in CI.
+ * - **Resilience / self-limiting secondary budget**: logs are the PRIMARY
+ *   evidence (fetched with the bounded retry). Spans are a SECONDARY fetch, run
+ *   best-effort inside a sub-budget carved from `limits.timeoutMs`
+ *   (`SPAN_BUDGET_FRACTION`) and bounded by the caller's abort signal. If the span
+ *   search is slow, fails, or is aborted, the log items still ship + an honest gap
+ *   — one API's slowness NEVER drops the other API's items, and the adapter always
+ *   resolves before the framework's per-source timeout fires.
+ * - **Descriptor-keyed query construction**: the query string is built strictly
+ *   from `descriptor.joinKeys` ∩ present keys; a requested key Datadog cannot use
+ *   becomes an honest {@link EvidenceGap}. Every declared join key is genuinely
+ *   applied (traceId → `@trace_id`, service → `service:`, url → `@http.url`, time
+ *   → filter from/to) — no silent no-op.
+ * - **Boundaries**: honors `limits.maxItems`/`maxBytes`/`timeoutMs`; the page
+ *   limit caps results server-side so there is no pagination walk beyond
+ *   `maxItems`; every request carries `CRUMBTRAIL_USER_AGENT`; the API/app keys live
+ *   only in the request headers, never in a gap, stat, thrown message, or log.
+ * - **Redaction stays at the framework boundary** (`redact.ts`); this file only
+ *   populates the fields that boundary scrubs (`brief`, `after`, `ref.url`).
+ */
+/** Env var carrying the Datadog API key. Required. */
+declare const DATADOG_API_KEY_ENV = "CRUMBTRAIL_DATADOG_API_KEY";
+/** Env var carrying the Datadog application key. Required. */
+declare const DATADOG_APP_KEY_ENV = "CRUMBTRAIL_DATADOG_APP_KEY";
+/** Env var carrying the Datadog site (datadoghq.com | datadoghq.eu | us3… ). Optional. */
+declare const DATADOG_SITE_ENV = "CRUMBTRAIL_DATADOG_SITE";
+/** Default site when {@link DATADOG_SITE_ENV} is unset. */
+declare const DATADOG_DEFAULT_SITE = "datadoghq.com";
+/** Presence of these two ⇒ the provider is configured (mirrors ticket clients).
+ *  Site has a default so it is not required. */
+declare const DATADOG_AUTH_FIELDS: string[];
+declare const DATADOG_DESCRIPTOR: EvidenceSourceDescriptor;
+interface DatadogSourceConfig {
+    apiKey: string;
+    appKey: string;
+    /** Datadog site, e.g. "datadoghq.com". Defaults to {@link DATADOG_DEFAULT_SITE}. */
+    site?: string;
+    /** Injectable transport. Defaults to global `fetch`. Tests pass a stub. */
+    fetchImpl?: typeof fetch;
+}
+interface DatadogQueryPlan {
+    /** The Datadog search query string (may be empty ⇒ time-window only). */
+    queryString: string;
+    /** Join keys actually used to narrow beyond the time window, best-first. */
+    usedKeys: EvidenceJoinKey[];
+    /** Honest gaps: a requested key Datadog cannot filter by. */
+    gaps: EvidenceGap[];
+}
+/**
+ * Build the Datadog query from `descriptor.joinKeys` ∩ present keys. The same
+ * query string filters both the logs and spans search bodies.
+ * Precedence: a `@trace_id:<id>` term when a trace is present (tightest), plus
+ * additive `service:<svc>` and `@http.url:<url>` terms for whichever of those
+ * keys is present. Any requested key Datadog does NOT support (requestId,
+ * sessionId, release, user) yields a gap so the bundle states plainly what
+ * filtered the result.
+ */
+declare function buildDatadogQuery(query: EvidenceQuery): DatadogQueryPlan;
+/** Minimal shape of a Datadog Logs Search v2 result row. */
+interface DatadogLog {
+    id?: string;
+    attributes?: {
+        timestamp?: string | number;
+        message?: string;
+        service?: string;
+        status?: string;
+    };
+}
+/** Minimal shape of a Datadog Spans Search v2 result row. */
+interface DatadogSpan {
+    id?: string;
+    attributes?: {
+        start_timestamp?: string | number;
+        resource_name?: string;
+        operation_name?: string;
+        service?: string;
+        duration?: number;
+        trace_id?: string;
+        span_id?: string;
+    };
+}
+/**
+ * Derive the Datadog app UI base for deep links from the API site.
+ * `datadoghq.com`/`.eu` use an `app.` subdomain; regional sites (us3/us5/ap1)
+ * already carry their subdomain, so the site is the app host.
+ */
+declare function datadogAppBase(site: string): string;
+/** One Datadog log → neutral evidence.v1 item (lane "logs"). Pure. */
+declare function normalizeDatadogLog(log: DatadogLog, appBase: string, queryString: string, window: {
+    start: number;
+    end: number;
+}): EvidenceItem;
+/** One Datadog span → neutral evidence.v1 item (lane "network"). Pure. */
+declare function normalizeDatadogSpan(span: DatadogSpan, appBase: string): EvidenceItem;
+declare class DatadogEvidenceSource implements EvidenceSource {
+    readonly descriptor: EvidenceSourceDescriptor;
+    private readonly apiKey;
+    private readonly appKey;
+    private readonly site;
+    private readonly apiBase;
+    private readonly appBase;
+    private readonly fetchImpl;
+    constructor(config: DatadogSourceConfig);
+    private headers;
+    private post;
+    /** Cheap authenticated no-op: validate the API key. */
+    health(signal?: AbortSignal): Promise<SourceHealth>;
+    /** PRIMARY: Logs Search v2. Bounded retry — this is the evidence we must ship. */
+    private searchLogs;
+    /** SECONDARY: Spans Search v2. Single attempt on purpose — it runs inside a
+     *  sub-budget, so retrying would risk blowing the per-source timeout. */
+    private searchSpans;
+    /**
+     * Best-effort span search inside a sub-budget carved from `limits.timeoutMs`
+     * and bounded by the caller's abort signal. A slow/failed/aborted span search
+     * leaves `spans` empty (→ the log items still ship) and flips `incomplete`.
+     * Mirrors Sentry's `enrichStackHeads`.
+     */
+    private fetchSpansBestEffort;
+    fetchEvidence(query: EvidenceQuery, signal?: AbortSignal): Promise<EvidenceSourceResult>;
+}
+/** Registry entry: build a Datadog source from env when its auth fields are set. */
+declare const datadogEvidenceProvider: EvidenceSourceProvider;
+
+/**
+ * PostHog evidence adapter — built to the Sentry reference shape (`sentry.ts`)
+ * and the Datadog two-API shape (`datadog.ts`). Query-at-incident-time pull:
+ * given a located incident window and the correlation keys known for it, ask
+ * PostHog's Events REST API (primary) and Session-Recordings list API
+ * (secondary) for records in that window, and normalize each into the neutral
+ * `evidence.v1` contract. Zero-copy — nothing PostHog returns is persisted; only
+ * the derived bundle is.
+ *
+ * Load-bearing patterns mirrored from the references:
+ * - **Injectable transport**: constructor takes `fetchImpl?: typeof fetch`
+ *   defaulting to global `fetch`; contract tests inject a fixture-routing stub so
+ *   there is zero network in CI.
+ * - **Resilience / self-limiting secondary budget**: events are the PRIMARY
+ *   evidence (fetched with the bounded retry). Session recordings are a SECONDARY
+ *   fetch, run best-effort inside a sub-budget carved from `limits.timeoutMs`
+ *   (`RECORDINGS_BUDGET_FRACTION`) and bounded by the caller's abort signal. If
+ *   the recordings list is slow, fails, or is aborted, the event items still ship
+ *   + an honest gap — one API's slowness NEVER drops the other API's items, and
+ *   the adapter always resolves before the framework's per-source timeout fires.
+ * - **Descriptor-keyed query construction**: the filters are built strictly from
+ *   `descriptor.joinKeys` ∩ present keys; a requested key PostHog cannot use
+ *   becomes an honest {@link EvidenceGap}. Every declared join key is genuinely
+ *   applied (user → `distinct_id`, sessionId → `$session_id` event property +
+ *   recordings `session_ids`, url → `$current_url` event property, time → the
+ *   window) — no silent no-op.
+ * - **Recordings are LINK-ONLY**: the adapter lists recordings and links them by
+ *   `ref.url` (a replay player deep link). It NEVER downloads or stores recording
+ *   content — `before`/`after` stay null. See the brief's Out of Scope.
+ * - **Boundaries**: honors `limits.maxItems`/`maxBytes`/`timeoutMs`; the `limit`
+ *   arg caps results server-side so there is no pagination walk beyond
+ *   `maxItems`; every request carries `CRUMBTRAIL_USER_AGENT`; the personal API key
+ *   lives only in the Authorization header, never in a gap, stat, thrown message,
+ *   or log.
+ * - **Redaction stays at the framework boundary** (`redact.ts`); this file only
+ *   populates the fields that boundary scrubs (`brief`, `after`, `ref.url`).
+ */
+/** Env var carrying the PostHog personal API key (Bearer). Required. */
+declare const POSTHOG_API_KEY_ENV = "CRUMBTRAIL_POSTHOG_API_KEY";
+/** Env var carrying the PostHog project id (numeric or short id). Required. */
+declare const POSTHOG_PROJECT_ID_ENV = "CRUMBTRAIL_POSTHOG_PROJECT_ID";
+/** Env var overriding the API/UI host (self-hosted or EU cloud). Optional. */
+declare const POSTHOG_HOST_ENV = "CRUMBTRAIL_POSTHOG_HOST";
+/** Default cloud host when {@link POSTHOG_HOST_ENV} is unset. The API and UI
+ *  share this origin, so it also anchors the deep links. Use
+ *  `https://eu.posthog.com` (EU cloud) or your self-hosted origin otherwise. */
+declare const POSTHOG_DEFAULT_HOST = "https://us.posthog.com";
+/** Presence of these two ⇒ the provider is configured (mirrors ticket clients).
+ *  Host has a default so it is not required. */
+declare const POSTHOG_AUTH_FIELDS: string[];
+declare const POSTHOG_DESCRIPTOR: EvidenceSourceDescriptor;
+interface PostHogSourceConfig {
+    apiKey: string;
+    projectId: string;
+    /** API/UI host, no trailing slash. Defaults to {@link POSTHOG_DEFAULT_HOST}. */
+    host?: string;
+    /** Injectable transport. Defaults to global `fetch`. Tests pass a stub. */
+    fetchImpl?: typeof fetch;
+}
+/** One PostHog event-property filter (the `properties` query param is a JSON
+ *  array of these). */
+interface PostHogPropertyFilter {
+    key: string;
+    value: string;
+    operator: "exact";
+    type: "event";
+}
+interface PostHogQueryPlan {
+    /** `distinct_id` filter (from the `user` key), applied to events + recordings. */
+    distinctId?: string;
+    /** `$session_id` filter (from the `sessionId` key), applied to recordings too. */
+    sessionId?: string;
+    /** Event-property filters (`$session_id`, `$current_url`) for the events query. */
+    properties: PostHogPropertyFilter[];
+    /** Join keys actually used to narrow beyond the time window, best-first. */
+    usedKeys: EvidenceJoinKey[];
+    /** Honest gaps: a requested key PostHog cannot filter by. */
+    gaps: EvidenceGap[];
+}
+/**
+ * Build the PostHog query from `descriptor.joinKeys` ∩ present keys.
+ * Precedence: `user` → `distinct_id` (the person filter, tightest and applied to
+ * BOTH the events and recordings requests); `sessionId` → a `$session_id` event
+ * property filter AND the recordings `session_ids` filter; `url` → a
+ * `$current_url` event property filter. The time window is always applied via the
+ * request date range. Any requested key PostHog does NOT support (traceId,
+ * requestId, release, service) yields a gap so the bundle states plainly what
+ * filtered the result.
+ */
+declare function buildPostHogQuery(query: EvidenceQuery): PostHogQueryPlan;
+/** Minimal shape of a PostHog event row (from `GET /api/projects/{id}/events/`). */
+interface PostHogEvent {
+    id?: string;
+    distinct_id?: string;
+    event?: string;
+    timestamp?: string;
+    properties?: Record<string, unknown>;
+}
+/** Minimal shape of a PostHog session-recording row (from the list endpoint). */
+interface PostHogRecording {
+    id?: string;
+    distinct_id?: string;
+    start_time?: string;
+    end_time?: string;
+    /** Recording length in SECONDS (PostHog reports `recording_duration`). */
+    recording_duration?: number;
+}
+/** Human-readable recording duration, e.g. "45s" or "3m 20s". */
+declare function formatDuration(seconds: number | undefined): string;
+/** A person-scoped deep link when the distinct id is known (the reliable link),
+ *  else the project activity explorer. */
+declare function posthogEventDeepLink(appBase: string, projectId: string, distinctId: string | undefined): string;
+/** The replay player deep link for a recording (LINK-ONLY — no content fetched). */
+declare function posthogRecordingDeepLink(appBase: string, projectId: string, recordingId: string): string;
+/** One PostHog event → neutral evidence.v1 item (lane "browser"/"flow"). Pure. */
+declare function normalizePostHogEvent(event: PostHogEvent, appBase: string, projectId: string): EvidenceItem;
+/**
+ * One PostHog session recording → neutral evidence.v1 item (lane "flow").
+ * LINK-ONLY: the value is the replay deep link in `ref.url`; NO recording content
+ * is fetched or stored, so `before`/`after` are null. Pure.
+ */
+declare function normalizePostHogRecording(recording: PostHogRecording, appBase: string, projectId: string): EvidenceItem;
+declare class PostHogEvidenceSource implements EvidenceSource {
+    readonly descriptor: EvidenceSourceDescriptor;
+    private readonly apiKey;
+    private readonly projectId;
+    private readonly appBase;
+    private readonly fetchImpl;
+    constructor(config: PostHogSourceConfig);
+    private headers;
+    private getJson;
+    private projectPath;
+    /** Cheap authenticated no-op: GET the project endpoint. */
+    health(signal?: AbortSignal): Promise<SourceHealth>;
+    /** PRIMARY: events query. Bounded retry — this is the evidence we must ship. */
+    private searchEvents;
+    /** SECONDARY: session-recordings list. Single attempt on purpose — it runs
+     *  inside a sub-budget, so retrying would risk blowing the per-source timeout.
+     *  LINK-ONLY: this lists recordings; it NEVER reads snapshot/content blobs. */
+    private searchRecordings;
+    /**
+     * Best-effort recordings list inside a sub-budget carved from `limits.timeoutMs`
+     * and bounded by the caller's abort signal. A slow/failed/aborted list leaves
+     * `recordings` empty (→ the event items still ship) and flips `incomplete`.
+     * Mirrors Datadog's `fetchSpansBestEffort`.
+     */
+    private fetchRecordingsBestEffort;
+    fetchEvidence(query: EvidenceQuery, signal?: AbortSignal): Promise<EvidenceSourceResult>;
+}
+/** Registry entry: build a PostHog source from env when its auth fields are set. */
+declare const posthogEvidenceProvider: EvidenceSourceProvider;
+
+/**
+ * Cloudflare evidence adapter — built to the Sentry reference shape
+ * (`sentry.ts`). Cloudflare has no ad-hoc log-query API on most plans, so this
+ * adapter reads a **Logpush-to-R2 sink**: the client configures a Logpush job
+ * that streams HTTP-request logs (or Workers Trace Events) as gzipped NDJSON
+ * objects into an R2 bucket, and this adapter lists+reads the objects whose
+ * time-partitioned keys fall inside the located incident window.
+ *
+ * R2 exposes an **S3-compatible API**, so we reuse the hand-rolled
+ * {@link signSigV4} signer (service `s3`, region `auto`, R2 access key/secret,
+ * endpoint `https://{account}.r2.cloudflarestorage.com`) rather than adding an
+ * S3 SDK — the same zero-dependency decision made for CloudWatch. R2 egress is
+ * FREE, so bulk reads cost nothing (the one provider where this is true), but we
+ * still bound total work by `maxItems`/`maxBytes`/`timeoutMs` — we never walk the
+ * whole bucket; truncation is recorded as a gap. Zero-copy: nothing R2 returns is
+ * persisted; only the derived bundle is.
+ *
+ * Load-bearing patterns mirrored from the reference adapters:
+ * - **Injectable transport**: constructor takes `fetchImpl?: typeof fetch`
+ *   defaulting to global `fetch`; contract tests inject a fixture-routing stub so
+ *   there is zero network in CI.
+ * - **Descriptor-keyed filtering**: R2 has no server-side query, so `url` and
+ *   `requestId` are applied as LINE-LEVEL filters after read; `time` is applied
+ *   both by mapping the window to the minimal set of date-partitioned object keys
+ *   AND at the line level. Any requested key the dataset cannot use becomes an
+ *   honest {@link EvidenceGap} rather than a silent no-op.
+ * - **Self-limiting read budget**: listing is the PRIMARY step (bounded retry);
+ *   object reads fan out with capped concurrency inside a sub-budget carved from
+ *   `limits.timeoutMs` (`READ_BUDGET_FRACTION`) so the adapter resolves BEFORE the
+ *   framework's per-source timeout fires. Objects that could not be read in budget
+ *   degrade to whatever was parsed + an honest gap, never "no items."
+ * - **Resilience / source-unavailable marker**: a hard failure (bucket
+ *   unreachable / auth fail) that yielded zero items self-degrades to a
+ *   `kind: "source-unavailable"` gap → `ok:false`; partial success stays
+ *   `ok:true` (see `fetch-all.ts`).
+ * - **Secrets discipline**: the R2 secret lives ONLY inside the signer; it never
+ *   appears in a gap, stat, thrown message, or log.
+ * - **Redaction stays at the framework boundary** (`redact.ts`); this file only
+ *   populates the fields that boundary scrubs (`brief`, `after`, `ref.url`).
+ */
+/** Env var carrying the Cloudflare account id (R2 endpoint host). Required. */
+declare const CLOUDFLARE_R2_ACCOUNT_ID_ENV = "CRUMBTRAIL_CLOUDFLARE_R2_ACCOUNT_ID";
+/** Env var carrying the R2 access key id. Required. */
+declare const CLOUDFLARE_R2_ACCESS_KEY_ID_ENV = "CRUMBTRAIL_CLOUDFLARE_R2_ACCESS_KEY_ID";
+/** Env var carrying the R2 secret access key. Required. */
+declare const CLOUDFLARE_R2_SECRET_ACCESS_KEY_ENV = "CRUMBTRAIL_CLOUDFLARE_R2_SECRET_ACCESS_KEY";
+/** Env var carrying the R2 bucket name Logpush writes into. Required. */
+declare const CLOUDFLARE_R2_BUCKET_ENV = "CRUMBTRAIL_CLOUDFLARE_R2_BUCKET";
+/** Env var carrying the key prefix BEFORE the `{DATE}` Logpush partition. Optional. */
+declare const CLOUDFLARE_R2_PREFIX_ENV = "CRUMBTRAIL_CLOUDFLARE_R2_PREFIX";
+/** Env var selecting the Logpush dataset. Optional (default http_requests). */
+declare const CLOUDFLARE_R2_DATASET_ENV = "CRUMBTRAIL_CLOUDFLARE_R2_DATASET";
+/** Env var overriding the R2 endpoint host (testing/localstack). Optional. */
+declare const CLOUDFLARE_R2_ENDPOINT_ENV = "CRUMBTRAIL_CLOUDFLARE_R2_ENDPOINT";
+/** Logpush datasets this adapter knows how to normalize. */
+type CloudflareDataset = "http_requests" | "workers_trace_events";
+/** Presence of these four ⇒ the provider is configured (mirrors ticket clients).
+ *  Prefix, dataset, and endpoint have defaults so they are not required. */
+declare const CLOUDFLARE_AUTH_FIELDS: string[];
+declare const CLOUDFLARE_DESCRIPTOR: EvidenceSourceDescriptor;
+interface CloudflareSourceConfig {
+    accountId: string;
+    accessKeyId: string;
+    secretAccessKey: string;
+    bucket: string;
+    /** Key prefix BEFORE the `{DATE}` Logpush partition (no leading slash). */
+    prefix?: string;
+    /** Logpush dataset. Defaults to http_requests. */
+    dataset?: CloudflareDataset;
+    /** Endpoint host override (no trailing slash). Defaults to the R2 endpoint. */
+    endpoint?: string;
+    /** Injectable transport. Defaults to global `fetch`. Tests pass a stub. */
+    fetchImpl?: typeof fetch;
+}
+interface CloudflarePlan {
+    /** Case-insensitive substring the request URL must contain, when url keyed. */
+    urlFilter?: string;
+    /** Exact RayID/request id a line must carry, when requestId keyed. */
+    requestIdFilter?: string;
+    /** Join keys actually used to narrow beyond the time window, best-first. */
+    usedKeys: EvidenceJoinKey[];
+    /** Honest gaps: a requested key this dataset cannot filter by. */
+    gaps: EvidenceGap[];
+}
+/**
+ * Build the line-level filter plan from `descriptor.joinKeys` ∩ present keys.
+ * R2 has no query API, so filters are applied per NDJSON line after read:
+ * `requestId` → exact match on the line's RayID (both datasets); `url` →
+ * case-insensitive substring on the request URL (http_requests only — Workers
+ * Trace Events carry no URL, so a requested `url` becomes a gap). Any requested
+ * key outside the descriptor (traceId, sessionId, release, user, service) yields
+ * a gap so the bundle states plainly what filtered the result.
+ */
+declare function buildCloudflarePlan(query: EvidenceQuery, dataset: CloudflareDataset): CloudflarePlan;
+declare class CloudflareEvidenceSource implements EvidenceSource {
+    readonly descriptor: EvidenceSourceDescriptor;
+    private readonly accessKeyId;
+    private readonly secretAccessKey;
+    private readonly bucket;
+    private readonly prefix;
+    private readonly dataset;
+    private readonly endpoint;
+    private readonly fetchImpl;
+    constructor(config: CloudflareSourceConfig);
+    /** One SigV4-signed GET against R2 (S3 API). The secret lives only in the
+     *  signer; `x-amz-content-sha256` (empty-body hash) is signed as S3 requires.
+     *  Returns the raw Response so callers can read text() or arrayBuffer(). */
+    private signedGet;
+    /** Build a ListObjectsV2 URL for a key prefix, capped to a single page. */
+    private listUrl;
+    private objectUrl;
+    private listObjects;
+    private readObject;
+    /** Cheap authenticated no-op: ListObjectsV2 on the bucket, max-keys 1. */
+    health(signal?: AbortSignal): Promise<SourceHealth>;
+    fetchEvidence(query: EvidenceQuery, signal?: AbortSignal): Promise<EvidenceSourceResult>;
+}
+/** Registry entry: build a Cloudflare source from env when its auth fields are set. */
+declare const cloudflareEvidenceProvider: EvidenceSourceProvider;
+
+interface JsonRpcRequest {
+    jsonrpc: "2.0";
+    id?: number | string;
+    method: string;
+    params?: Record<string, unknown>;
+}
+interface JsonRpcResponse {
+    jsonrpc: "2.0";
+    id: number | string;
+    result?: unknown;
+    error?: {
+        code: number;
+        message: string;
+        data?: unknown;
+    };
+}
+interface McpServerConfig {
+    outputDir: string;
+    /**
+     * Test-only seam: overrides how the git-host client is constructed for
+     * `solveContext`'s intent-inference path. Production code leaves this
+     * unset and builds a `GitHubRestClient` from `CRUMBTRAIL_GITHUB_TOKEN`.
+     */
+    gitHostClientFactory?: (gitHost: {
+        owner: string;
+        repo: string;
+    }) => GitHostClient;
+    /**
+     * Test-only seam: overrides how the ticket connector is constructed for
+     * `solveContext`'s `ticket` input. Production code leaves this unset and
+     * builds a connector from the documented provider env vars.
+     */
+    ticketConnectorFactory?: (provider: TicketProvider) => TicketConnector;
+    /**
+     * Test-only seam: overrides how the on-demand `Reproducer` is constructed
+     * for `solveContext`'s thin-evidence reproduction path. Production code
+     * leaves this unset, which disables reproduction entirely — the gate
+     * short-circuits and no reproducer (not even `NoopReproducer`) is built.
+     */
+    reproducerFactory?: () => Reproducer;
+    /**
+     * Test-only seam: overrides how the client's evidence sources are constructed
+     * for `solveContext`'s adapter phase (sessionless Mode A + blended). Production
+     * code leaves this unset and builds them from env via evidenceSourcesFromEnv().
+     */
+    evidenceSourcesFactory?: () => EvidenceSource[];
+}
+declare class McpServer {
+    private outputDir;
+    private bugQueue;
+    private gitHostClientFactory?;
+    private ticketConnectorFactory?;
+    private reproducerFactory?;
+    private evidenceSourcesFactory?;
+    constructor(config: McpServerConfig);
+    /** Evidence sources for solveContext's adapter phase — injected in tests,
+     *  built from env in production. */
+    private evidenceSources;
+    start(): void;
+    handleMessage(msg: JsonRpcRequest): Promise<JsonRpcResponse | null>;
+    private callTool;
+    private sessionDir;
+    private isSafeSessionId;
+    private readEvents;
+    /**
+     * Resolve a tool's args to a target directory. A bug is a named window into
+     * a session: if `bugId` is present, gate on its existence and resolve to the
+     * bug's dir; otherwise resolve to the session's dir. Session targets are not
+     * pre-checked here (existence is discovered downstream by the specific tool,
+     * matching pre-seam behavior), so this only errors for a missing bug.
+     */
+    private resolveTarget;
+    /** Shared kind/after/before filtering; per-tool limit/compact stay caller-side. */
+    private filterEvents;
+    /** Shared error-context body for both session and bug tools. */
+    private errorContextFor;
+    /** Shared failed-requests body; notFoundMsg differs per caller. */
+    private failedRequestsFor;
+    private toolListSessions;
+    private sessionMetadataMatches;
+    private toolGetIndex;
+    private toolGetEvents;
+    private toolGetErrorContext;
+    private toolGetFailedRequests;
+    private toolGetLinkedRequestContext;
+    private matchesFullStackGap;
+    private linkedRequestDiagnostics;
+    private fullStackCorrelationStatus;
+    private compactLinkedFullStackRequest;
+    private compactFullStackGap;
+    private compactFrontendEvidence;
+    private compactBackendEvidence;
+    private compactEventRef;
+    private compactCorrelation;
+    private compactFrontendError;
+    private compactBackendError;
+    /** Parses the optional `maxTokens` arg. `{}` when absent; error when invalid. */
+    private maxTokensOf;
+    /**
+     * Shared budgeted-response path: fills `payload[itemsKey]` from `items` in
+     * their given rank order via the one shared fillToBudget helper, then
+     * attaches `tokenEstimate` (of the final serialized payload) and, when
+     * anything was dropped, a structured `dropReport`. `onKept` lets a caller
+     * patch dependent fields (e.g. getWindow's returned/truncated) after the
+     * fill. Deterministic; logs drops to stderr only (stdout carries only
+     * JSON-RPC frames).
+     */
+    private budgetedTextResult;
+    /**
+     * Shared response path for getFixContext and getLatestIssue. Unbudgeted
+     * stays byte-identical to the raw contract; budgeted fills ranked_candidates
+     * in candidate-rank order (refs are candidate ids resolvable via getEvidence).
+     */
+    private fixContextResult;
+    private toolGetFixContext;
+    /**
+     * One-call entry point: resolve the latest finalized session with
+     * error-class evidence via the SAME resolveLatestIssue shared with the
+     * `fix-context --latest` CLI flag, then reuse the getFixContext response
+     * path (including optional maxTokens budgeting — its only input).
+     */
+    private toolGetLatestIssue;
+    private toolGetRegressionContext;
+    private toolSolveContext;
+    private toolListDistinctBugs;
+    private toolGetRecurrence;
+    private toolGetBug;
+    /** Reads the grouped distinct bugs from the finalized hot-plane bundle (llm.json, else bundle.json). */
+    private readDistinctBugs;
+    private recurrenceRollups;
+    private compactRecurrence;
+    private signatureForBug;
+    /**
+     * Recall past issues that rhyme with a session or a free-text description. In
+     * cloud deployments (CRUMBTRAIL_CLOUD_URL + CRUMBTRAIL_API_KEY set) this delegates
+     * to the org-wide semantic index; otherwise it scans the local session store
+     * with a text-overlap + facet analogue so self-hosted users still get recall
+     * without a vector DB.
+     */
+    private toolRecallSimilarIssues;
+    /** Adapt this server's storage readers to the recall engine's injected seam.
+     *  Delegates to the shared buildRecallStore so the MCP tool and the inner
+     *  /api/solve-context endpoint locate against an identical store. */
+    private recallStore;
+    private isDistinctBugRecord;
+    private firstString;
+    private toolGetSessionManifest;
+    private synthesizeManifest;
+    private toolGetWindow;
+    private toolGetEvidence;
+    private windowCap;
+    private sessionExists;
+    /** Reads the sanitized cold event stream first; falls back to legacy/plain events when zstd is absent. */
+    private readColdEvents;
+    private parseEvents;
+    private readCandidatesJsonl;
+    private readSignatureEntries;
+    private readInteractiveElement;
+    /**
+     * Reads the finalized hot-plane interactive-element identity map (bundle.browserEvidence
+     * .interactiveElements). Prefers llm.json then bundle.json — the same finalized artifacts
+     * listDistinctBugs/getBug read. Values are already redaction-sanitized at bundle build time;
+     * this only ever surfaces those redacted descriptors, never raw masked values.
+     */
+    private readInteractiveElements;
+    private toolResolveSignature;
+    private toolLocateInteractiveElements;
+    private locateLimit;
+    /**
+     * Builds a deterministic, redaction-safe descriptor for one signature by combining the
+     * finalized interactive-element map (label/text, tag, occurrence count, path) with the
+     * cold-plane signature dictionary (first-seen, first event kind). Returns undefined when the
+     * signature is absent from the interactive-element map.
+     */
+    private buildElementDescriptor;
+    /**
+     * Pure descriptor builder over already-read interactive-element and signature-dictionary
+     * arrays. Hoisting the reads out of callers keeps locateInteractiveElements O(n) instead of
+     * re-parsing the bundle/signature files once per element.
+     */
+    private buildElementDescriptorFrom;
+    private affordanceFor;
+    private readJsonRecord;
+    private toolGetStorageSnapshot;
+    private toolGetCookieChanges;
+    private toolGetStorageChanges;
+    private toolGetTranscript;
+    private toolGetFrame;
+    private toolGetFrameById;
+    private toolListBugs;
+    private toolGetBugReport;
+    private toolGetBugEvents;
+    private toolGetBugErrorContext;
+    private toolGetBugFailedRequests;
+    private toolGetBugVoiceTranscript;
+    private toolResolveBug;
+    private toolGetBugLlmContext;
+    private safeGetBug;
+    private safeGetBugLlmContext;
+}
+
+/** A database row diff correlated to the primary window. See {@link LlmBundleDbDiff}. */
+type FixContextDbDiff = LlmBundleDbDiff;
+type FixContextDbRead = LlmBundleDbRead;
+type FixContextDbActivity = LlmBundleDbActivity;
+/**
+ * Versioned, ranked, correlated, LLM-ready "hand it to the model" bundle for a finalized
+ * session. This is the keystone fix-context contract (V2.5).
+ *
+ * The shape is intentionally stable: `primary_window.db_diffs` defaults to an empty array
+ * and `environment` defaults to null so later checkpoints (CP5 DB diffing, CP3 environment
+ * capture) can populate them without breaking the contract.
+ */
+/**
+ * @stability stable
+ * Version-bump policy follows the same Fork A decision as fusion.v1 — see
+ * wargames/wargames/01-solve-context-wargame-fields.md.
+ */
+declare const FIX_CONTEXT_SCHEMA_VERSION: "fix-context.v1";
+interface FixContextSession {
+    id: string;
+    name?: string;
+    app?: string;
+    source?: string;
+    startMs: number;
+    endMs: number;
+    durationMs: number;
+}
+interface FixContextReproHint {
+    title?: string;
+    detector?: string;
+    severity?: EvidenceCandidate["severity"];
+    route?: string;
+    target?: EvidenceCandidate["anchor"]["target"];
+    elementLabel?: string;
+    errorCode?: string;
+    message?: string;
+    requestId?: string;
+    offsetMs?: number;
+}
+interface FixContextPrimaryWindow {
+    frontend: {
+        window: {
+            start: number;
+            end: number;
+            windowId: string;
+        } | null;
+        anchor: EvidenceCandidate["anchor"] | null;
+        requests: LlmBundleFrontendRequestEvidenceSummary[];
+    };
+    backend: {
+        requests: LlmBundleBackendRequestEvidenceSummary[];
+    };
+    /**
+     * Database row diffs correlated to the primary window (CP5 DB diffing). Empty when the session
+     * captured no `db.diff` events in the window. Consumers MUST treat `[]` as "no DB evidence".
+     */
+    db_diffs: FixContextDbDiff[];
+    /**
+     * Database rows read in the primary window (`db.read`, pre-state capture). Empty when read
+     * capture is disabled or no reads matched the primary request/window.
+     */
+    db_reads: FixContextDbRead[];
+    /**
+     * OTel DB span activity in the primary window. These are statements/operations only, never
+     * before/after row diffs.
+     */
+    db_activity: FixContextDbActivity[];
+}
+/** One downstream symptom of the primary root cause, resolved from `ranked_candidates`. */
+interface FixContextCausalSymptom {
+    id: string;
+    detector: string;
+    title: string;
+    attributionConfidence?: CausalConfidence;
+}
+/**
+ * The primary root-cause → symptom chain, derived ONLY from causal fields already present on the
+ * ranked candidates (CP3). `null` when the primary candidate is isolated or has no attributed
+ * symptoms. Purely a projection — no attribution is recomputed here.
+ */
+interface FixContextCausalChain {
+    root: {
+        id: string;
+        detector: string;
+        title: string;
+    };
+    symptoms: FixContextCausalSymptom[];
+}
+interface FixContext {
+    schemaVersion: typeof FIX_CONTEXT_SCHEMA_VERSION;
+    session: FixContextSession;
+    ranked_candidates: EvidenceCandidate[];
+    primary_window: FixContextPrimaryWindow;
+    /**
+     * Account/environment state snapshot. Defaults to `null`; CP3 (environment capture)
+     * populates this. Consumers MUST treat null as "not captured".
+     */
+    environment: Record<string, unknown> | null;
+    /**
+     * Primary root-cause → symptom chain projected from the ranked candidates' causal fields (CP4).
+     * `null` when the top candidate is isolated or attributes no symptoms. Consumers MUST treat null
+     * as "no causal structure surfaced".
+     */
+    causal_chain: FixContextCausalChain | null;
+    repro_hint: FixContextReproHint | null;
+}
+interface BuildFixContextOptions {
+    /** Base sessions directory used to resolve a bare session id to a directory. */
+    outputDir?: string;
+}
+declare class FixContextError extends Error {
+    readonly code: "session-not-found";
+    constructor(code: "session-not-found", message: string);
+}
+/**
+ * Builds the fix-context contract for a finalized session by reading hot-plane artifacts
+ * (index.json, candidates.jsonl, llm.json). It never reads raw NDJSON at query time.
+ */
+declare function buildFixContext(sessionDirOrId: string, opts?: BuildFixContextOptions): FixContext;
+
+type HeaderValue = string | number | readonly string[] | undefined;
+type BackendRequestHeaders = Record<string, HeaderValue>;
+interface BackendRequestEventInput {
+    method?: string;
+    url?: string;
+    originalUrl?: string;
+    path?: string;
+    route?: string;
+    headers?: BackendRequestHeaders;
+    sessionId?: string;
+    requestId?: string;
+    sessionStartedAt?: number | Date;
+    now?: number;
+}
+
+/**
+ * Default sensitive column names whose values are always dropped before a `db.diff` event rests.
+ * Hosts can extend this list per shim via `redactColumns`. Matching is name-based and
+ * normalization-aware (case-insensitive; `apiKey`/`api_key`/`APIKEY` all match `api_key`).
+ */
+declare const DEFAULT_SENSITIVE_DB_COLUMNS: readonly ["password", "token", "secret", "api_key", "ssn"];
+
+interface BuildDbDiffEventInput {
+    /** Engine that produced the mutation. Defaults to `"postgres"` for back-compat. */
+    engine?: DbEngine;
+    op: DbDiffOp;
+    table: string;
+    /** Primary-key column→value map, or `null` when it could not be resolved. */
+    pk: Record<string, unknown> | null;
+    /** Post-image of the affected row (insert/update). */
+    after?: Record<string, unknown>;
+    /** Pre-image of the affected row (deletes, or updates with before-capture enabled). */
+    before?: Record<string, unknown>;
+    /** Set only on image-less statement-level fallback events (pk `null`, no after/before). */
+    rowCount?: number;
+    /** Correlation id; MUST equal the active request's traceId/requestId. */
+    requestId: string;
+    sessionId?: string;
+    /** Extra sensitive column names to drop, on top of {@link DEFAULT_SENSITIVE_DB_COLUMNS}. */
+    redactColumns?: readonly string[];
+    now?: number;
+    sessionStartedAt?: number | Date;
+}
+/**
+ * Builds the canonical `k:'db.diff'` event for one changed row. Sensitive columns are dropped from
+ * `after`/`before`/`pk` via the shared redaction policy BEFORE the event is returned, so secret
+ * values never rest in the event. The event carries `requestId` so it lands in the same evidence
+ * window as the `backend.req.*` and front-end network events of the request that caused the write.
+ */
+declare function buildDbDiffEvent(input: BuildDbDiffEventInput): BugEvent;
+
+interface BuildDbReadEventInput {
+    /** Engine that produced the read. Defaults to `"postgres"` for back-compat. */
+    engine?: DbEngine;
+    table: string;
+    pk: Record<string, unknown> | null;
+    row: Record<string, unknown>;
+    requestId: string;
+    sessionId?: string;
+    redactColumns?: readonly string[];
+    now?: number;
+    sessionStartedAt?: number | Date;
+}
+interface BuildDbReadBulkEventInput {
+    /** Engine that produced the read. Defaults to `"postgres"` for back-compat. */
+    engine?: DbEngine;
+    table: string;
+    requestId: string;
+    rowCount: number;
+    emittedRows: number;
+    samplePks: Array<Record<string, unknown>>;
+    sessionId?: string;
+    now?: number;
+    sessionStartedAt?: number | Date;
+}
+declare function buildDbReadEvent(input: BuildDbReadEventInput): BugEvent;
+declare function buildDbReadBulkEvent(input: BuildDbReadBulkEventInput): BugEvent;
+
+/**
+ * Options accepted by every `instrument*` adapter. Every field is engine-agnostic; the Postgres
+ * shim keeps `InstrumentPgClientOptions` as a back-compat alias of this type.
+ */
+interface InstrumentDbClientOptions {
+    /** Active request correlation id (equals the request's traceId). */
+    requestId?: string;
+    /** Lazily resolve the active request id (e.g. from AsyncLocalStorage); wins when `requestId` is absent. */
+    getRequestId?: () => string | undefined;
+    sessionId?: string;
+    /** Sink for emitted `db.diff` events (e.g. forward to `sendBackendEvent`). */
+    emit: (event: BugEvent) => void;
+    /** When true, capture the pre-image of UPDATE rows via a SELECT-by-WHERE before mutating. */
+    captureBefore?: boolean;
+    /** When true, capture capped/redacted SELECT result rows as pre-state read evidence. Default off. */
+    captureReads?: boolean;
+    /** Extra sensitive column names dropped on top of the defaults. */
+    redactColumns?: readonly string[];
+    /** Primary-key columns per table; defaults to `['id']` for unlisted tables. */
+    pkColumns?: Record<string, readonly string[]>;
+    /** Maximum per-row `db.diff` events to emit for one statement before adding a bulk summary. */
+    maxRowsPerStatement?: number;
+    /** Maximum per-row `db.read` events to emit for one SELECT before adding a bulk summary. */
+    maxReadRowsPerStatement?: number;
+    /** Maximum per-row `db.read` events to emit for one request scope. */
+    maxReadRowsPerRequest?: number;
+    now?: () => number;
+    sessionStartedAt?: number | Date;
+}
+
+/**
+ * Dialect-aware SQL statement parsing shared by every DB adapter. The parsers are deliberately
+ * conservative: they recognize single-table INSERT/UPDATE/DELETE and simple SELECT-FROM shapes
+ * across Postgres, MySQL, MSSQL, and SQLite quoting/keyword variants, and return `undefined` for
+ * anything they do not understand so callers degrade to "no diff" rather than mis-instrument.
+ */
+interface ParsedMutation {
+    op: DbDiffOp;
+    table: string;
+    whereClause?: string;
+}
+interface ParsedRead {
+    table: string;
+}
+/** Parses op + table (+ WHERE clause) from a SQL statement. Returns undefined for non-mutations. */
+declare function parseMutation(sql: string): ParsedMutation | undefined;
+/** Parses the first table from a simple SELECT statement. Returns undefined for non-reads. */
+declare function parseRead(sql: string): ParsedRead | undefined;
+
+/**
+ * Minimal duck-typed view of a `pg` Client/Pool. We never import `pg` at module top-level — the
+ * host injects its own client/pool, so `pg` stays an optional peer and tests use a fake client.
+ */
+interface DuckTypedPgQueryResult {
+    rows?: unknown[];
+    rowCount?: number | null;
+    command?: string;
+}
+interface DuckTypedPgClient {
+    query(text: unknown, params?: unknown): Promise<DuckTypedPgQueryResult>;
+}
+/** Back-compat alias: the Postgres shim shares the engine-agnostic option shape. */
+type InstrumentPgClientOptions = InstrumentDbClientOptions;
+/**
+ * Wraps a duck-typed `pg` client/pool so INSERT/UPDATE/DELETE statements executed within a request
+ * scope record a `db.diff` event (op, table, primary key, after-image; before-image behind
+ * `captureBefore`). The shim appends `RETURNING *` when absent to read the after-image, and reads
+ * the result rows otherwise. Only the promise-returning `query(text, params)` form is instrumented;
+ * config-object and callback forms pass straight through. Engine is Postgres only; the builder is
+ * driver-agnostic so other engines can slot in later.
+ *
+ * Limitations: trigger/cascade side effects and rows changed by other tables are not captured; the
+ * pre-image SELECT for `captureBefore` reuses the statement's WHERE clause + params, so it supports
+ * single-table UPDATEs (not CTEs, joins, or sub-selects).
+ */
+declare function instrumentPgClient<T extends DuckTypedPgClient>(client: T, options: InstrumentPgClientOptions): T;
+
+/**
+ * Minimal duck-typed view of a `mysql2/promise` connection/pool. We never import `mysql2` at module
+ * top-level — the host injects its own client, so `mysql2` stays an optional peer and tests use a
+ * fake client. Both `query` and `execute` resolve `[rowsOrResultHeader, fields]`.
+ */
+interface DuckTypedMysqlClient {
+    query(sql: unknown, values?: unknown): Promise<unknown>;
+    execute?(sql: unknown, values?: unknown): Promise<unknown>;
+}
+/** The mysql2 result-set header duck shape for a mutation (INSERT/UPDATE/DELETE). */
+interface DuckTypedMysqlResultHeader {
+    affectedRows: number;
+    insertId?: number;
+}
+/**
+ * Wraps a duck-typed `mysql2/promise` client/pool so INSERT/UPDATE/DELETE statements executed within
+ * a request scope record a `db.diff` event (op, table, primary key, after-image; before-image behind
+ * `captureBefore`). MySQL has no `RETURNING`, so images come from best-effort extra SELECTs:
+ *
+ * - INSERT: a single-row auto-increment insert (`affectedRows === 1`, positive `insertId`, single-column
+ *   pk) is re-read by `insertId`; anything else (multi-row, missing insertId, composite pk) degrades to
+ *   an image-less `db.diff` carrying `rowCount`.
+ * - UPDATE: a pre-SELECT (WHERE + trailing params) captures pks (and before-images when `captureBefore`),
+ *   then a post-SELECT by those pks captures after-images.
+ * - DELETE: a pre-SELECT (WHERE + trailing params) captures the before-images.
+ *
+ * Both the promise-returning `query(sql, values)` and `execute(sql, values)` forms are instrumented
+ * (identically); non-string sql / config-object forms pass straight through. The host statement is
+ * never altered and runs exactly once — every capture SELECT and emit is wrapped so instrumentation
+ * can never fail, double-execute, or alter the host query; the host result is returned unchanged.
+ *
+ * Limitations: trigger/cascade side effects and rows changed by other tables are not captured; the
+ * WHERE-based pre-image SELECT supports single-table UPDATE/DELETE (not CTEs, joins, or sub-selects).
+ */
+declare function instrumentMysqlClient<T extends DuckTypedMysqlClient>(client: T, options: InstrumentDbClientOptions): T;
+
+/**
+ * Minimal duck-typed view of an `mssql`-package result. We never import `mssql` at module top level —
+ * the host injects its own pool, so `mssql` stays an optional peer and tests use a fake pool. Only the
+ * fields the shim reads are typed; every other property (`output`, `returnValue`, …) rides through the
+ * host-visible result untouched.
+ */
+interface DuckTypedMssqlResult {
+    recordset?: unknown[];
+    recordsets?: unknown[][];
+    rowsAffected?: number[];
+    [key: string]: unknown;
+}
+/** Duck-typed view of an `mssql` Request (`pool.request()`), recording `input()` and running `query()`. */
+interface DuckTypedMssqlRequest {
+    input(name: string, ...rest: unknown[]): unknown;
+    query(text: unknown): Promise<DuckTypedMssqlResult>;
+    [key: string]: unknown;
+}
+/** Duck-typed view of an `mssql` ConnectionPool. `query` (the convenience single-string form) is optional. */
+interface DuckTypedMssqlPool {
+    request(): DuckTypedMssqlRequest;
+    query?(text: unknown, ...rest: unknown[]): Promise<DuckTypedMssqlResult>;
+}
+/**
+ * Wraps a duck-typed `mssql` pool so INSERT/UPDATE/DELETE statements executed within a request scope
+ * record a `db.diff` event (op, table, primary key, after-image; before-image behind `captureBefore`).
+ * After-images are read by injecting an `OUTPUT INSERTED.*` / `OUTPUT DELETED.*` clause into the
+ * statement (no extra round trip); the injected rows are consumed for diffs and then stripped from the
+ * host-visible result, so the caller sees exactly what the un-instrumented statement would have
+ * returned. SELECTs are optionally captured as read evidence (`captureReads`).
+ *
+ * Never-fail guarantees:
+ *  - Parse/correlation failures, missing request scope, unparseable SQL → the original statement runs
+ *    untouched.
+ *  - A pre-injection safety gate (`scanStatementSafety`) refuses to edit any statement we cannot
+ *    confidently tokenize as a single statement — multi-statement batches, unterminated
+ *    strings/comments, and quote-bearing comments run the ORIGINAL untouched (image-less diff), so the
+ *    host never receives corrupt T-SQL or loses a caller recordset.
+ *  - The host mutation executes exactly once. The only re-run is the compile-class fallback (errors
+ *    334 / 156 / 102), which fail at COMPILE time before any rows change, so re-running the ORIGINAL
+ *    text on a fresh request with replayed inputs is safe. Every other error propagates as-is.
+ *  - All capture/emit work is wrapped; a failure degrades to fewer/no diffs, never to a failed host
+ *    query. When a mutation clearly ran but no images are obtainable, one image-less `db.diff`
+ *    (`pk: null`, `rowCount`) still records the write.
+ */
+declare function instrumentMssqlPool<T extends DuckTypedMssqlPool>(pool: T, options: InstrumentDbClientOptions): T;
+
+/**
+ * Minimal duck-typed view of a better-sqlite3 / `node:sqlite` statement. The host injects the real
+ * database, so the sqlite driver stays an optional peer and tests use a synchronous fake. `run`
+ * returns the mutation summary (`changes` + `lastInsertRowid`); `all`/`get` read rows back.
+ */
+interface DuckTypedSqliteStatement {
+    run(...params: unknown[]): unknown;
+    all(...params: unknown[]): unknown;
+    get(...params: unknown[]): unknown;
+    [key: string]: unknown;
+}
+interface DuckTypedSqliteRunResult {
+    changes: number;
+    lastInsertRowid: number | bigint;
+}
+/** Minimal duck-typed view of a better-sqlite3 / `node:sqlite` database: `prepare(sql)` → statement. */
+interface DuckTypedSqliteDatabase {
+    prepare(sql: unknown, ...rest: unknown[]): DuckTypedSqliteStatement;
+    [key: string]: unknown;
+}
+/**
+ * Wraps a duck-typed better-sqlite3 / `node:sqlite` database so INSERT/UPDATE/DELETE statements
+ * executed within a request scope record a `db.diff` event (op, table, primary key, after-image;
+ * before-image behind `captureBefore`), and SELECTs optionally record `db.read` evidence. Everything
+ * is fully synchronous — the sync driver's `run`/`all` return values are observed inline, so events
+ * are visible the instant the host call returns.
+ *
+ * The database is wrapped with a Proxy that intercepts `prepare`; the returned statement is itself
+ * proxied so `run` (mutations) and `all` (reads, when `captureReads`) are instrumented and every
+ * other member (`get`, `iterate`, `pluck`, …) binds straight through. Non-string or unparseable SQL
+ * yields the real statement untouched.
+ *
+ * After-images come from post-SELECTs (INSERT by `rowid`, UPDATE by the pks captured in a pre-SELECT)
+ * — the host's SQL text is never rewritten, so `run()` returns exactly what the real driver produced.
+ * Every capture step is wrapped: a failing pre/post-SELECT, missing rowid, WITHOUT-ROWID table, or
+ * emit error degrades to fewer/no images (image-less fallback carrying `rowCount`), never a failed
+ * host query.
+ *
+ * Limitations: trigger/cascade side effects and rows changed via other tables are not captured; the
+ * pre-image SELECT reuses the statement's WHERE clause + params, so it supports single-table
+ * UPDATE/DELETE (not CTEs, joins, or sub-selects).
+ */
+declare function instrumentSqliteDatabase<T extends DuckTypedSqliteDatabase>(db: T, options: InstrumentDbClientOptions): T;
+
+interface DbRequestContext {
+    requestId: string;
+    sessionId?: string;
+}
+/**
+ * Resolves the `db.diff` request scope from the SAME inputs `backend.req.*` events use — the
+ * `X-Crumbtrail-Request-Id` / `X-Crumbtrail-Session-Id` headers (where the request id already equals
+ * the W3C trace id) or explicit options. This guarantees a `db.diff` produced inside a request
+ * shares the request's requestId, instead of inventing a parallel correlation scheme.
+ */
+declare function resolveDbRequestContext(input: BackendRequestEventInput): DbRequestContext;
+
+/**
+ * Concise, hot-plane-only summary of a finalized session. `crumbtrail-server inspect <session>` reads
+ * the session manifest (manifest.json) when present and otherwise falls back to index.json. It
+ * never reads raw events.ndjson — counts come from the pre-computed index/manifest.
+ */
+interface SessionInspectionArtifact {
+    name: string;
+    bytes: number;
+}
+interface SessionInspection {
+    id: string;
+    durationMs: number;
+    eventCount: number;
+    errorCount: number;
+    failedRequestCount: number;
+    candidateCount: number;
+    truncated: boolean;
+    /** Which hot-plane artifact the summary was primarily derived from. */
+    source: "manifest" | "index";
+    /**
+     * Earliest error-class evidence timestamp stamped into llm.json by bundle build.
+     * Omitted when the bundle carries no latency self-measurement (or llm.json is absent).
+     */
+    firstErrorEventAt?: number;
+    /** Self-measured detect-to-bundle latency (ms) stamped into llm.json. Omitted when absent. */
+    detectToBundleMs?: number;
+    artifacts: SessionInspectionArtifact[];
+}
+interface InspectSessionOptions {
+    /** Base sessions directory used to resolve a bare session id to a directory. */
+    outputDir?: string;
+}
+declare class InspectError extends Error {
+    readonly code: "session-not-found";
+    constructor(code: "session-not-found", message: string);
+}
+declare function inspectSession(sessionDirOrId: string, opts?: InspectSessionOptions): SessionInspection;
+declare function formatInspection(inspection: SessionInspection): string;
+
+/**
+ * Resolve the crumbtrail-node package version by walking up from this module to the nearest
+ * package.json named `crumbtrail-node`. The same layout holds in dev/test (src/version.ts →
+ * ../package.json) and in the published build (dist/cli.cjs → ../package.json), so no
+ * build-time baking is required.
+ */
+declare function readPackageVersion(): string;
+
+type ProviderId = "datadog" | "otel" | "sentry" | "grafana" | "splunk";
+interface ProviderRecipe {
+    id: ProviderId;
+    title: string;
+    docFile: string;
+    description: string;
+    config: string;
+    notes: string[];
+}
+declare const PROVIDER_RECIPES: ProviderRecipe[];
+declare const PROVIDER_IDS: ProviderId[];
+declare function isProviderId(value: string | undefined): value is ProviderId;
+declare function getProviderRecipe(provider: ProviderId): ProviderRecipe;
+declare function renderProviderConfig(provider: ProviderId, endpoint?: string): string;
+declare function renderProviderCliOutput(provider: ProviderId, endpoint?: string): string;
+declare function renderProviderDoc(provider: ProviderId, endpoint?: string): string;
+declare function renderProviderReadme(): string;
+
+type BackendIntakeWarningKind = "missing-session" | "missing-fetch" | "fetch-rejected" | "http-error" | "malformed-response";
+interface BackendIntakeWarning {
+    kind: BackendIntakeWarningKind;
+    message: string;
+    status?: number;
+    sessionId?: string;
+    requestId?: string;
+    eventKind?: string;
+}
+type FetchLike$1 = (input: string | URL, init?: FetchInitLike) => Promise<ResponseLike>;
+type HeadersInitLike = Record<string, string>;
+interface FetchInitLike {
+    method?: string;
+    headers?: HeadersInitLike;
+    body?: string;
+    signal?: AbortSignal;
+}
+interface ResponseLike {
+    ok: boolean;
+    status: number;
+    text?: () => Promise<string>;
+    json?: () => Promise<unknown>;
+}
+interface SendBackendEventOptions {
+    event: BugEvent;
+    sessionId?: string;
+    endpoint?: string;
+    authToken?: string;
+    fetch?: FetchLike$1;
+    signal?: AbortSignal;
+    onWarning?: (warning: BackendIntakeWarning) => void;
+}
+declare function sendBackendEvent(options: SendBackendEventOptions): Promise<void>;
+
+type CrumbtrailExpressNext = (error?: unknown) => void;
+type CrumbtrailExpressErrorNext = (error: unknown) => void;
+interface CrumbtrailExpressRequest {
+    method?: string;
+    url?: string;
+    originalUrl?: string;
+    path?: string;
+    route?: string | {
+        path?: unknown;
+    };
+    headers?: BackendRequestHeaders;
+}
+interface CrumbtrailExpressResponse {
+    statusCode?: number;
+    once?: (event: "finish", listener: () => void) => unknown;
+}
+type CrumbtrailExpressMiddleware = (req: CrumbtrailExpressRequest, res: CrumbtrailExpressResponse, next: CrumbtrailExpressNext) => void;
+type CrumbtrailExpressErrorMiddleware = (error: unknown, req: CrumbtrailExpressRequest, res: CrumbtrailExpressResponse, next: CrumbtrailExpressErrorNext) => void;
+type RequestValueResolver = string | undefined | ((req: CrumbtrailExpressRequest) => string | undefined);
+type SessionStartedAtResolver = number | Date | undefined | ((req: CrumbtrailExpressRequest) => number | Date | undefined);
+type NowResolver = () => number;
+type FetchLike = Parameters<typeof sendBackendEvent>[0]["fetch"];
+interface CrumbtrailExpressOptions {
+    sessionId?: RequestValueResolver;
+    requestId?: RequestValueResolver;
+    endpoint?: string;
+    authToken?: string;
+    fetch?: FetchLike;
+    signal?: AbortSignal;
+    sessionStartedAt?: SessionStartedAtResolver;
+    now?: NowResolver;
+    onWarning?: (warning: BackendIntakeWarning) => void;
+}
+declare function createCrumbtrailExpressMiddleware(options?: CrumbtrailExpressOptions): CrumbtrailExpressMiddleware;
+declare function createCrumbtrailExpressErrorMiddleware(options?: CrumbtrailExpressOptions): CrumbtrailExpressErrorMiddleware;
+
+interface HeadlessSessionOptions {
+    endpoint: string;
+    sessionId: string;
+    metadata?: Record<string, unknown>;
+    authToken?: string;
+    fetchImpl?: typeof fetch;
+}
+interface HeadlessSession {
+    sessionId: string;
+    record(events: BugEvent | BugEvent[]): Promise<void>;
+    end(): Promise<Record<string, unknown>>;
+}
+declare function startHeadlessSession(options: HeadlessSessionOptions): Promise<HeadlessSession>;
+
+declare const SESSION_COMPARE_SCHEMA_VERSION: "session-compare.v1";
+type ComparisonVerdict = "regression" | "clean";
+type ComparisonConfidence = "high" | "medium" | "low";
+interface SessionComparison {
+    schemaVersion: typeof SESSION_COMPARE_SCHEMA_VERSION;
+    verdict: ComparisonVerdict;
+    confidence: ComparisonConfidence;
+    a: SessionRef;
+    b: SessionRef;
+    alignment: {
+        matchedSteps: number;
+        unmatchedA: number;
+        unmatchedB: number;
+    };
+    divergences: Divergence[];
+    noise: {
+        suppressedCount: number;
+        rules: string[];
+    };
+    /** Neutral, complete projection of divergences. Consumed by cloud fusion. */
+    evidence: EvidenceItem[];
+    /** Intent inference. Empty until the git-host connector (slice 2) lands. */
+    intent: IntentSignal[];
+}
+interface SessionRef {
+    sessionId: string;
+    release?: string;
+    build?: string;
+}
+interface Divergence {
+    plane: "flow" | "network" | "db" | "env";
+    kind: string;
+    sig?: string;
+    requestId?: string;
+    table?: string;
+    pk?: Record<string, unknown>;
+    before: unknown;
+    after: unknown;
+    brief: string;
+}
+interface CompareOptions {
+    alignmentWindow?: number;
+    disableNoiseRules?: string[];
+}
+
+declare class CompareError extends Error {
+    constructor(message: string);
+}
+declare function compareSessions(aDir: string, bDir: string, options?: CompareOptions): Promise<SessionComparison>;
+
+declare function renderCompareReport(comparison: SessionComparison): string;
+declare function formatComparisonSummary(comparison: SessionComparison): string;
+
+declare const REGRESSION_CONTEXT_SCHEMA_VERSION: "regression-context.v1";
+interface RegressionContext {
+    schemaVersion: typeof REGRESSION_CONTEXT_SCHEMA_VERSION;
+    comparison: SessionComparison;
+    divergent_interaction: {
+        sig: string;
+        label: string;
+        path: string;
+    } | null;
+    causal_window: {
+        requestIds: string[];
+        t0: number;
+        t1: number;
+        hints: string[];
+    } | null;
+    db_rows: Array<{
+        table: string;
+        pk: Record<string, unknown>;
+        before: unknown;
+        after: unknown;
+    }>;
+    repro_hint: string;
+}
+declare function buildRegressionContext(comparison: SessionComparison, bDir: string): RegressionContext;
+
+/** The subset of the locate envelope this builder reads. `outcome` is the only
+ *  signal that flips the comment shape; `confidence` is display-only. */
+interface AdvisoryCommentMatch {
+    outcome: "matched" | "inconclusive";
+    confidence: number;
+    reasons?: string[];
+}
+/** One evidence gap surfaced from the bundle (mirrors core's EvidenceGap). */
+interface AdvisoryCommentGap {
+    lane?: string;
+    reason: string;
+    suggestion?: string;
+}
+/**
+ * Correlation keys carried INTO the ticket so the reader can line the matched
+ * incident up against their own logs/traces. Every value here must come from the
+ * located evidence — NEVER fabricated. Rendered only in the matched variant.
+ */
+interface AdvisoryCommentCorrelation {
+    /** The located session id (match.sessionId). */
+    sessionId?: string;
+    /** Distinct request/trace ids pulled from the bundle's evidence refs. */
+    requestIds?: string[];
+}
+interface BuildAdvisoryCommentInput {
+    match: AdvisoryCommentMatch;
+    /** Public link to the persisted bundle (`/api/bundles/:id`). Always rendered. */
+    bundleUrl: string;
+    gaps?: AdvisoryCommentGap[];
+    /** Correlation keys from the located evidence (matched variant only). */
+    correlation?: AdvisoryCommentCorrelation;
+}
+/** A minimally-typed ADF node. ADF is an open tree; we only build the handful of
+ *  node kinds we need (doc/paragraph/text/link/bulletList/listItem). */
+interface AdfNode {
+    type: string;
+    [key: string]: unknown;
+}
+interface AdfDoc {
+    version: 1;
+    type: "doc";
+    content: AdfNode[];
+}
+/**
+ * Build the advisory ADF comment. Two shapes, chosen by `match.outcome`:
+ *
+ * - matched: names that a candidate incident was located, shows the rounded
+ *   confidence as an advisory percentage, lists the match reasons in plain
+ *   language (if any), carries the correlation keys (located session + up to a
+ *   few request/trace ids, when the evidence has them) onto the ticket, and
+ *   links the full evidence bundle.
+ * - inconclusive: states honestly that no recorded incident matched, lists the
+ *   evidence gaps (if any) so the reader knows what is missing, and still links
+ *   the (empty) bundle. It fabricates no match and reports no percentage.
+ *
+ * Pure and side-effect free — unit-testable in isolation.
+ */
+declare function buildAdvisoryComment(input: BuildAdvisoryCommentInput): AdfDoc;
+
+declare const REPLAY_RESULT_SCHEMA_VERSION: "replay-result.v1";
+type StepResolution = 'exact' | 'role-label' | 'structural' | 'failed';
+interface ReplayStepResult {
+    index: number;
+    sig: string;
+    action: string;
+    resolution: StepResolution;
+    durationMs: number;
+}
+interface ReplayDivergence {
+    index: number;
+    sig: string;
+    reason: string;
+}
+interface ReplayResult {
+    schemaVersion: typeof REPLAY_RESULT_SCHEMA_VERSION;
+    sourceSessionId: string;
+    actuatedSessionId: string;
+    steps: ReplayStepResult[];
+    divergences: ReplayDivergence[];
+    completed: boolean;
+}
+declare function buildReplayResult(input: {
+    sourceSessionId: string;
+    actuatedSessionId: string;
+    steps: ReplayStepResult[];
+    divergences: ReplayDivergence[];
+    completed: boolean;
+}): ReplayResult;
+declare function parseReplayResult(raw: unknown): ReplayResult;
+declare function writeReplayResult(filePath: string, result: ReplayResult): void;
+
+/**
+ * Canonical event kind emitted for an auto-captured backend error (crash or
+ * console.error). It is deliberately NOT `backend.req.error` (that kind is
+ * request-scoped and joins on a requestId this hook never has) and NOT
+ * `backend.error` (that literal is a causal-graph NODE kind, not an event kind —
+ * reusing it would collide). This request-less kind carries only the error and
+ * the hook that surfaced it.
+ *
+ * Downstream wiring (all requestId-free, so every site fits): causal-graph
+ * `nodeKindFor` maps it onto the `backend.error` node kind, post-process
+ * `FULL_STACK_BACKEND_KINDS` + `mergeBackendEvent` summarize its error, and
+ * evidence-index surfaces it as a `backend_request_error` candidate + error
+ * moment — mirroring `backend.req.error` at each site.
+ */
+declare const AUTO_CAPTURE_ERROR_EVENT = "backend.uncaught";
+/** Hooks a crash/console capture handler can surface an error from. */
+type AutoCaptureSource = "uncaughtException" | "unhandledRejection" | "console.error";
+interface AutoCaptureOptions {
+    /** Ingest endpoint (baked into the injected snippet by the CLI). */
+    endpoint: string;
+    /**
+     * Ingest key. Defaults to `process.env.CRUMBTRAIL_KEY`, which is populated from
+     * the project's `.env` by `autoCapture` itself (see `loadEnv`).
+     */
+    authToken?: string;
+    /** Explicit session id; a stable auto-generated one is used when omitted. */
+    sessionId?: string;
+    /** Extra session metadata merged into the headless session start. */
+    metadata?: Record<string, unknown>;
+    /** Injectable fetch (tests); forwarded to `startHeadlessSession`. */
+    fetchImpl?: typeof fetch;
+    /**
+     * When true (default) attempt `process.loadEnvFile()` so the key in `.env`
+     * lands in `process.env` before the session starts. Guarded: a no-op when the
+     * API is unavailable (<20.12) or the `.env` file is missing/unreadable.
+     */
+    loadEnv?: boolean;
+    /** Console object to patch (tests). Defaults to the global `console`. */
+    consoleImpl?: Pick<Console, "error">;
+    /** Process to hook (tests). Defaults to the global `process`. */
+    processImpl?: NodeJS.Process;
+    /**
+     * Called after a best-effort record on an unrecoverable crash
+     * (`uncaughtException` / `unhandledRejection`) IN PLACE of `process.exit`.
+     * Tests inject this to assert crash semantics are preserved without killing
+     * the runner. Defaults to `process.exit`.
+     */
+    onCrashExit?: (code: number) => void;
+}
+interface AutoCaptureHandle {
+    /** The started session id, when the session start succeeded. */
+    sessionId?: string;
+    /** Restore the original console.error and remove the process hooks. */
+    stop(): void;
+}
+/**
+ * Install best-effort backend crash + console.error capture and start a headless
+ * ingest session. Returns a handle whose `stop()` restores every hook.
+ *
+ * Crash semantics are preserved: on `uncaughtException` (and a suppressed
+ * `unhandledRejection`) we best-effort record the error, bound-flush it (race the
+ * record against a hard ~150ms ceiling so the crash event can actually reach
+ * ingest before the process dies), then exit non-zero — the bounded flush can
+ * never hang, and capture never converts a crash into survival.
+ */
+declare function autoCapture(options: AutoCaptureOptions): Promise<AutoCaptureHandle>;
+
+interface OtlpAnyValue {
+    stringValue?: string;
+    boolValue?: boolean;
+    intValue?: string | number;
+    doubleValue?: number;
+    arrayValue?: {
+        values?: OtlpAnyValue[];
+    };
+    kvlistValue?: {
+        values?: OtlpKeyValue[];
+    };
+    bytesValue?: string;
+}
+interface OtlpKeyValue {
+    key?: string;
+    value?: OtlpAnyValue;
+}
+
+interface OtlpSpan {
+    traceId?: string;
+    spanId?: string;
+    parentSpanId?: string;
+    name?: string;
+    kind?: number;
+    startTimeUnixNano?: string | number;
+    endTimeUnixNano?: string | number;
+    attributes?: OtlpKeyValue[];
+    status?: {
+        code?: number;
+        message?: string;
+    };
+}
+interface OtlpScopeSpans {
+    scope?: {
+        name?: string;
+        version?: string;
+    };
+    spans?: OtlpSpan[];
+}
+interface OtlpResourceSpans {
+    resource?: {
+        attributes?: OtlpKeyValue[];
+    };
+    scopeSpans?: OtlpScopeSpans[];
+}
+interface OtlpTraceRequest {
+    resourceSpans?: OtlpResourceSpans[];
+}
+interface OtlpLogRecord {
+    timeUnixNano?: string | number;
+    observedTimeUnixNano?: string | number;
+    severityText?: string;
+    severityNumber?: number;
+    body?: {
+        stringValue?: string;
+    };
+    traceId?: string;
+    spanId?: string;
+    attributes?: OtlpKeyValue[];
+}
+interface OtlpScopeLogs {
+    scope?: {
+        name?: string;
+    };
+    logRecords?: OtlpLogRecord[];
+}
+interface OtlpResourceLogs {
+    resource?: {
+        attributes?: OtlpKeyValue[];
+    };
+    scopeLogs?: OtlpScopeLogs[];
+}
+interface OtlpLogsRequest {
+    resourceLogs?: OtlpResourceLogs[];
+}
+
+declare function decodeOtlpTraceProtobuf(buffer: Uint8Array): OtlpTraceRequest;
+declare function decodeOtlpLogsProtobuf(buffer: Uint8Array): OtlpLogsRequest;
+
+export { AUTO_CAPTURE_ERROR_EVENT, type AdapterEvidence, type AdapterSourceStats, type AdfDoc, type AdfNode, type AdvisoryCommentGap, type AdvisoryCommentMatch, type AutoCaptureHandle, type AutoCaptureOptions, type AutoCaptureSource, type BoundedRetryOptions, type BugQueueConfig, BugQueueManager, type BuildAdvisoryCommentInput, type BuildDbDiffEventInput, type BuildDbReadBulkEventInput, type BuildDbReadEventInput, type BuildFixContextOptions, CLOUDFLARE_AUTH_FIELDS, CLOUDFLARE_DESCRIPTOR, CLOUDFLARE_R2_ACCESS_KEY_ID_ENV, CLOUDFLARE_R2_ACCOUNT_ID_ENV, CLOUDFLARE_R2_BUCKET_ENV, CLOUDFLARE_R2_DATASET_ENV, CLOUDFLARE_R2_ENDPOINT_ENV, CLOUDFLARE_R2_PREFIX_ENV, CLOUDFLARE_R2_SECRET_ACCESS_KEY_ENV, CLOUDWATCH_ACCESS_KEY_ID_ENV, CLOUDWATCH_AUTH_FIELDS, CLOUDWATCH_DESCRIPTOR, CLOUDWATCH_ENDPOINT_ENV, CLOUDWATCH_LOG_GROUPS_ENV, CLOUDWATCH_REGION_ENV, CLOUDWATCH_SECRET_ACCESS_KEY_ENV, CLOUDWATCH_SESSION_TOKEN_ENV, CRUMBTRAIL_USER_AGENT, CloudWatchEvidenceSource, type CloudWatchQueryPlan, type CloudWatchResultRow, type CloudWatchSourceConfig, type CloudflareDataset, CloudflareEvidenceSource, type CloudflarePlan, type CloudflareSourceConfig, type CommentingTicketConnector, CompareError, type CompareOptions, type ComparisonConfidence, type ComparisonVerdict, type CrumbtrailExpressErrorMiddleware, type CrumbtrailExpressErrorNext, type CrumbtrailExpressMiddleware, type CrumbtrailExpressNext, type CrumbtrailExpressOptions, type CrumbtrailExpressRequest, type CrumbtrailExpressResponse, type BackendIntakeWarning as CrumbtrailExpressWarning, type BackendIntakeWarningKind as CrumbtrailExpressWarningKind, DATADOG_API_KEY_ENV, DATADOG_APP_KEY_ENV, DATADOG_AUTH_FIELDS, DATADOG_DEFAULT_SITE, DATADOG_DESCRIPTOR, DATADOG_SITE_ENV, DEFAULT_MAX_TOTAL_BYTES, DEFAULT_SENSITIVE_DB_COLUMNS, DEFAULT_SOURCE_TIMEOUT_MS, DEFAULT_SWEEP_CHECKPOINT_MS, DEFAULT_SWEEP_IDLE_MS, DEFAULT_SWEEP_INTERVAL_MS, DISTINCT_BUGS_SCHEMA_VERSION, DatadogEvidenceSource, type DatadogLog, type DatadogQueryPlan, type DatadogSourceConfig, type DatadogSpan, type DbRequestContext, type DistinctBug, type DistinctBugEvidenceRef, type DistinctBugRecurrence, type DistinctBugRecurrenceInput, type DistinctBugRecurrenceOccurrence, type DistinctBugSeverity, type Divergence, type DuckTypedMssqlPool, type DuckTypedMssqlRequest, type DuckTypedMssqlResult, type DuckTypedMysqlClient, type DuckTypedMysqlResultHeader, type DuckTypedPgClient, type DuckTypedPgQueryResult, type DuckTypedSqliteDatabase, type DuckTypedSqliteRunResult, type DuckTypedSqliteStatement, EVIDENCE_SOURCE_PROVIDERS, CRUMBTRAIL_USER_AGENT as EVIDENCE_SOURCE_USER_AGENT, type EvidenceSource, type EvidenceSourceProvider, FIX_CONTEXT_SCHEMA_VERSION, type FetchAdapterEvidenceOptions, FilesystemSessionStore, type FixContext, type FixContextDbDiff, type FixContextDbRead, FixContextError, type FixContextPrimaryWindow, type FixContextReproHint, type FixContextSession, type HeadlessSession, type HeadlessSessionOptions, InspectError, type InspectSessionOptions, type InstrumentDbClientOptions, type InstrumentPgClientOptions, type JiraAuth, type JiraBasicAuth, type JiraBearerAuth, JiraTicketClient, type JiraTicketClientConfig, type JiraTicketClientConfigLegacy, type JiraTicketClientConfigWithAuth, McpServer, type McpServerConfig, type OtlpLogsRequest, type OtlpResourceLogs, type OtlpResourceSpans, type OtlpTraceRequest, POSTHOG_API_KEY_ENV, POSTHOG_AUTH_FIELDS, POSTHOG_DEFAULT_HOST, POSTHOG_DESCRIPTOR, POSTHOG_HOST_ENV, POSTHOG_PROJECT_ID_ENV, PROVIDER_IDS, PROVIDER_RECIPES, type PostHogEvent, PostHogEvidenceSource, type PostHogPropertyFilter, type PostHogQueryPlan, type PostHogRecording, type PostHogSourceConfig, type ProviderId, type ProviderRecipe, REGRESSION_CONTEXT_SCHEMA_VERSION, REPLAY_RESULT_SCHEMA_VERSION, type RegressionContext, type ReplayDivergence, type ReplayResult, type ReplayStepResult, SENTRY_AUTH_FIELDS, SENTRY_AUTH_TOKEN_ENV, SENTRY_DEFAULT_HOST, SENTRY_DESCRIPTOR, SENTRY_HOST_ENV, SENTRY_ORG_ENV, SESSION_COMPARE_SCHEMA_VERSION, SPLUNK_AUTH_FIELDS, SPLUNK_DESCRIPTOR, SPLUNK_HOST_ENV, SPLUNK_INDEX_ENV, SPLUNK_TOKEN_ENV, SPLUNK_WEB_URL_ENV, SentryEvidenceSource, type SentryQueryPlan, type SentrySourceConfig, type BugReport as ServerBugReport, type ServerConfig, type SessionComparison, type SessionFileFlags, type SessionFinalizationResult, type SessionInspection, type SessionInspectionArtifact, type SessionListItem, SessionManager, type SessionStore, type SessionSummary, type SessionSweepOptions, type SessionSweepResult, type SessionSweeperHandle, type Severity, type SigV4Input, type SignedHeaders, type SourceHealth, SplunkEvidenceSource, type SplunkQueryPlan, type SplunkResultRow, type SplunkSourceConfig, type StepResolution, type TicketConnector, TicketError, type TicketProvider, autoCapture, buildAdvisoryComment, buildCloudWatchQuery, buildCloudflarePlan, buildDatadogQuery, buildDbDiffEvent, buildDbReadBulkEvent, buildDbReadEvent, buildDistinctBugSignature, buildFixContext, buildPostHogQuery, buildRegressionContext, buildReplayResult, buildSentryQuery, buildSessionSummary, buildSplunkQuery, cloudWatchDeepLink, cloudWatchEvidenceProvider, cloudflareEvidenceProvider, compareSessions, createCrumbtrailExpressErrorMiddleware, createCrumbtrailExpressMiddleware, createServer, datadogAppBase, datadogEvidenceProvider, decodeOtlpLogsProtobuf, decodeOtlpTraceProtobuf, defaultSessionStore, evidenceRequestHeaders, evidenceSourcesFromEnv, fetchAdapterEvidence, formatComparisonSummary, formatDuration, formatInspection, getProviderRecipe, groupDistinctBugRecurrences, groupDistinctBugs, inspectSession, instrumentMssqlPool, instrumentMysqlClient, instrumentPgClient, instrumentSqliteDatabase, isProviderId, jiraToSymptom, normalizeCloudWatchRow, normalizeDatadogLog, normalizeDatadogSpan, normalizePostHogEvent, normalizePostHogRecording, normalizeSentryIssue, normalizeSplunkRow, parseMutation, parseRead, parseReplayResult, posthogEventDeepLink, posthogEvidenceProvider, posthogRecordingDeepLink, readPackageVersion, redactEvidenceGap, redactEvidenceItem, redactSourceResult, registerEvidenceProvider, renderCompareReport, renderProviderCliOutput, renderProviderConfig, renderProviderDoc, renderProviderReadme, resolveDbRequestContext, sentryEvidenceProvider, signSigV4, splunkEvidenceProvider, splunkSearchDeepLink, splunkWebBase, startHeadlessSession, startSessionSweeper, sweepIdleSessions, withBoundedRetry, writeReplayResult };