executable-stories-formatters 1.9.1 → 1.10.0

package/dist/index.d.ts

@@ -1,33 +1,28 @@
-import { C as CIInfo$1, a as CIProvider, T as TestRunResult, b as TestCaseResult, S as StoryStep, D as DocEntry, c as TestStatus$1, N as NormalizedTicket, A as Attachment, d as DocPhase, O as OtelSpan, R as RawStatus, e as StepResult, f as RawAttachment, g as RawRun, h as RawCIInfo, i as StepKeyword$1, j as adaptJestRun, k as adaptPlaywrightRun, l as adaptVitestRun } from './index-CmEmALo3.js';
-export { m as CIInfo, n as CoverageSummary, J as JestAdapterOptions, o as JestAggregatedResult, p as JestFileResult, q as JestTestResult, r as OtelAttributeValue, P as PlaywrightAdapterOptions, s as PlaywrightAnnotation, t as PlaywrightAttachment, u as PlaywrightError, v as PlaywrightLocation, w as PlaywrightStatus, x as PlaywrightTestCase, y as PlaywrightTestResult, z as RawStepEvent, B as RawTestCase, E as STORY_META_KEY, F as StepMode, G as StoryFileReport, H as StoryMeta, I as TestCaseAttempt, K as TestCaseEvidence, V as VitestAdapterOptions, L as VitestSerializedError, M as VitestState, Q as VitestTestCase, U as VitestTestModule, W as VitestTestResult, X as toCIInfo, Y as toRawCIInfo } from './index-CmEmALo3.js';
-
-/**
- * Configuration options for ACL and formatters.
- */
-/** Options for canonicalizing raw run data */
-interface CanonicalizeOptions {
-    /** Attachment handling options */
-    attachments?: {
-        /** Max bytes before attachment becomes external link. Default: 512KB (524288) */
-        maxEmbedBytes?: number;
-        /** Directory for external attachments */
-        externalDir?: string;
-    };
-    /** Cucumber compatibility options */
-    cucumber?: {
-        /** Include trailing space in keywords (e.g., "Given "). Default: true */
-        keywordSpacing?: boolean;
-        /** Generate deterministic line numbers. Default: true */
-        deterministicLines?: boolean;
-    };
-    /** Default timestamps if not provided in raw data */
-    defaults?: {
-        /** Default start time (epoch ms). Default: Date.now() */
-        startedAtMs?: number;
-        /** Default finish time (epoch ms). Default: Date.now() */
-        finishedAtMs?: number;
-    };
-}
+import { TestRunResult, TestCaseResult, TestStatus, Attachment } from 'executable-stories-core/types/test-result';
+export { Attachment, CIInfo, CoverageSummary, StepResult, TestCaseAttempt, TestCaseEvidence, TestCaseResult, TestRunResult, TestStatus } from 'executable-stories-core/types/test-result';
+import { StoryStep, DocEntry, NormalizedTicket, StepKeyword } from 'executable-stories-core/types/story';
+export { DocEntry, DocPhase, NormalizedTicket, STORY_META_KEY, StepKeyword, StepMode, StoryMeta, StoryStep } from 'executable-stories-core/types/story';
+import { CIInfo, CIProvider } from 'executable-stories-core/types/ci';
+export { CIProvider, CIInfo as TypedCIInfo, toCIInfo, toRawCIInfo } from 'executable-stories-core/types/ci';
+import { adaptJestRun, adaptPlaywrightRun, adaptVitestRun } from './adapters.js';
+export { JestAdapterOptions, JestAggregatedResult, JestFileResult, JestTestResult, PlaywrightAdapterOptions, PlaywrightAnnotation, PlaywrightAttachment, PlaywrightError, PlaywrightLocation, PlaywrightStatus, PlaywrightTestCase, PlaywrightTestResult, StoryFileReport, VitestAdapterOptions, VitestSerializedError, VitestState, VitestTestCase, VitestTestModule, VitestTestResult } from './adapters.js';
+export { OtelAttributeValue, OtelSpan } from 'executable-stories-core/types/otel';
+import { RawCIInfo } from 'executable-stories-core/types/raw';
+export { RawAttachment, RawCIInfo, RawRun, RawStatus, RawStepEvent, RawTestCase } from 'executable-stories-core/types/raw';
+import { StoryReport, TestStatus as TestStatus$1, ReportStep } from 'executable-stories-core/types/story-report';
+export { ReportAttachment, ReportCIInfo, ReportCoverageSummary, ReportDocCode, ReportDocCustom, ReportDocEntry, ReportDocKv, ReportDocLink, ReportDocMermaid, ReportDocNote, ReportDocScreenshot, ReportDocSection, ReportDocTable, ReportDocTag, ReportFeature, ReportScenario, ReportStep, ReportSummary, ReportTicket, STORY_REPORT_SCHEMA_MAJOR, STORY_REPORT_SCHEMA_VERSION, StoryReport, StoryReportSchemaVersion } from 'executable-stories-core/types/story-report';
+export { ES_THEME_TOKENS_CSS, ES_THEME_TOKEN_VALUES } from 'executable-stories-core/theme/tokens';
+export { canonicalizeRun, deriveStepResults, generateRunId, generateTestCaseId, mergeStepResults, normalizeStatus, resolveAttachment, resolveAttachments, slugify } from 'executable-stories-core/converters/acl/index';
+export { ValidationResult, assertValidRun, validateCanonicalRun } from 'executable-stories-core/converters/acl/validate';
+export { RunState, advanceState, initialRunState } from 'executable-stories-core';
+export { toStoryReport } from 'executable-stories-core/converters/story-report';
+import { Envelope } from 'executable-stories-core/types/cucumber-messages';
+export { parseEnvelopes, parseNdjson } from 'executable-stories-core/converters/ndjson-parser';
+export { formatDuration, msToNanoseconds, nanosecondsToMs } from 'executable-stories-core/utils/duration';
+export { OtelTraceContext, resolveTraceUrl, tryGetActiveOtelContext } from 'executable-stories-core/utils/otel-detect';
+export { HtmlDocOptions, buildHtmlDocEntry } from 'executable-stories-core/utils/doc-builders';
+import { CanonicalizeOptions } from 'executable-stories-core/types/canonicalize';
+export { CanonicalizeOptions } from 'executable-stories-core/types/canonicalize';
 
 /**
  * Notification types for webhook integrations (Slack, Teams).
@@ -45,7 +40,7 @@ interface NotificationSummary {
         name: string;
         error?: string;
     }>;
-    ci?: CIInfo$1;
+    ci?: CIInfo;
     reportUrl?: string;
 }
 /** When to send notifications. */
@@ -560,7 +555,7 @@ interface ScenarioSnapshot {
     scenario: string;
     sourceFile: string;
     sourceLine: number;
-    status: TestStatus$1;
+    status: TestStatus;
     durationMs: number;
     tags: string[];
     titlePath: string[];
@@ -723,224 +718,576 @@ interface IJsonFeature {
     uri: string;
 }
 
-interface Formatter {
+/**
+ * The test-management port.
+ *
+ * One interface, one engine, adapters per provider. Everything the engine does
+ * — matching, planning, drift detection, lockfile bookkeeping, reporting — is
+ * written once against these types. An adapter's only job is to translate
+ * between them and a vendor API.
+ *
+ * Adding a provider is one file in `adapters/` plus one line in
+ * `adapters/index.ts`, with no edits to `engine.ts`. If a new adapter forces an
+ * engine change, this port is wrong and gets fixed then, on evidence.
+ *
+ * Every method except `listCases` is optional. A read-only provider implements
+ * `listCases` alone and still produces a full coverage report; the engine
+ * reports the missing capabilities in the plan instead of failing.
+ */
+/** A test case as it exists in the provider, normalized. */
+interface RemoteCase {
+    /** Provider-native id, e.g. TestRail "1234" or Xray "PROJ-42". */
+    id: string;
+    /** Canonical URL a human can open. */
+    url: string;
+    title: string;
+    /** Suite, folder, or component — whatever the provider groups by. */
+    section?: string;
+    /**
+     * The content the provider currently holds, when it can supply it.
+     *
+     * Drift detection hashes this, not what we sent: providers normalize markup
+     * on write, so hashing the request would flag every case as human-edited on
+     * the very next run.
+     */
+    body?: CaseBody;
+}
+/** A story projected into provider-neutral case content. */
+interface CaseBody {
+    title: string;
+    steps: ReadonlyArray<{
+        keyword: string;
+        text: string;
+    }>;
+    /** Story docs rendered to plain text/markdown; adapters convert as needed. */
+    description: string;
+    links: ReadonlyArray<{
+        label: string;
+        url: string;
+    }>;
+}
+/** Evidence uploaded alongside a result. */
+interface ResultAttachment {
+    filename: string;
+    mediaType: string;
+    body: Uint8Array;
+    role?: "screenshot" | "video" | "trace" | "log";
+}
+/** One execution record to push. */
+interface CaseResult {
+    caseId: string;
+    status: "passed" | "failed" | "skipped";
+    durationMs: number;
+    message?: string;
+    /** Deep link into the generated HTML report for this scenario. */
+    url?: string;
+    attachments?: ResultAttachment[];
+}
+/** What a provider did with a batch of results. */
+interface RecordResultsSummary {
+    /** Provider-native run/execution id, when one was created. */
+    runId?: string;
+    /** URL of the created run/execution, when the provider exposes one. */
+    runUrl?: string;
+    recorded: number;
+    /** Results the provider declined (e.g. no status mapping configured). */
+    skipped: Array<{
+        caseId: string;
+        reason: string;
+    }>;
+    attachmentsUploaded: number;
+}
+/**
+ * A test-management system, reduced to what the engine needs.
+ *
+ * `createCase`/`updateCase` return the resulting {@link RemoteCase} rather than
+ * just an id so the engine can hash the provider's own normalized copy.
+ */
+interface SyncProvider {
+    /** Stable key used in config, CLI args, and the lockfile. */
     name: string;
-    fileExtension?: string;
-    format(run: TestRunResult): string;
+    listCases(): Promise<RemoteCase[]>;
+    createCase?(body: CaseBody): Promise<RemoteCase>;
+    updateCase?(id: string, body: CaseBody): Promise<RemoteCase>;
+    recordResults?(results: CaseResult[]): Promise<RecordResultsSummary>;
+    /**
+     * Per-file limit. The engine skips oversized attachments and reports them in
+     * the plan, rather than letting an adapter die mid-upload with half a run
+     * already pushed.
+     */
+    maxAttachmentBytes?: number;
+    /** Human-readable target, shown in the plan header (e.g. "ACME / Regression"). */
+    describeTarget?(): string;
 }
-interface ExecutableStoriesConfig {
-    formatters?: Record<string, Formatter>;
+/** Injectable dependencies shared by every adapter. */
+interface AdapterDeps {
+    fetch: typeof globalThis.fetch;
+    logger: {
+        warn(msg: string): void;
+    };
 }
 
 /**
- * StoryReport — public, frozen contract for UI renderers.
+ * The sync lockfile: the binding between a behaviour in the codebase and a case
+ * in someone else's system.
  *
- * Distinct from internal TestRunResult. Pre-grouped feature → scenario tree,
- * with pre-computed summaries at every level. Adapter concerns (rawStatus,
- * projectName, titlePath) are stripped at the toStoryReport boundary.
+ * Committed to the repo on purpose. When CI creates a case, the lockfile diff
+ * shows up in the pull request that caused it, so a reviewer sees the new case
+ * and its link before it lands anywhere else.
  *
- * Versioning: semver-style "<major>.<minor>". Additive-only within a major.
- * Source of truth: schemas/story-report-v1.json. Types here must stay in sync.
+ * Keyed on `behaviourFingerprint` (content-derived) rather than the canonical
+ * test-case id (`sha1(sourceFile::scenario)`), which changes the moment someone
+ * renames a test or moves a file. Keying on the volatile id would orphan every
+ * case on the first rename, which is exactly how these integrations lose trust.
  */
 
-type StoryReportSchemaVersion = `1.${number}`;
-type TestStatus = "passed" | "failed" | "skipped" | "pending";
-type StepKeyword = "Given" | "When" | "Then" | "And" | "But";
-type StepMode = "normal" | "skip" | "only" | "todo" | "fails" | "concurrent";
-interface ReportSummary {
-    total: number;
-    passed: number;
-    failed: number;
-    skipped: number;
-    pending: number;
-    durationMs: number;
+declare const DEFAULT_LOCKFILE_PATH = ".executable-stories/sync.lock.json";
+/** One behaviour-to-case binding. */
+interface LockEntry {
+    /** Provider-native case id. */
+    caseId: string;
+    url: string;
+    /**
+     * Hash of the provider's normalized copy as of our last write. A mismatch on
+     * the next run means a human edited the case in the provider's UI.
+     */
+    hash: string;
+    /** Last known title, so orphan reports are readable without a remote lookup. */
+    title: string;
+    /**
+     * True only for cases this tool created.
+     *
+     * A case reached through a `story.tickets` id was authored by a human, so we
+     * push executions against it and never touch its body. Without this flag the
+     * first sync would silently overwrite hand-written cases, which is the single
+     * fastest way to lose a QA team.
+     */
+    owned: boolean;
 }
-interface ReportTicket {
-    id: string;
-    url?: string;
+interface Lockfile {
+    version: number;
+    /** provider name -> behaviour fingerprint -> entry */
+    providers: Record<string, Record<string, LockEntry>>;
 }
-interface ReportAttachment {
-    name: string;
-    mediaType: string;
-    body: string;
-    contentEncoding: "BASE64" | "IDENTITY";
+declare function emptyLockfile(): Lockfile;
+/**
+ * Hash provider-normalized case content.
+ *
+ * Deliberately excludes `links`: those embed report URLs that change with every
+ * CI run (build number, artifact host), and treating that churn as a human edit
+ * would make the drift guard fire constantly and get switched off.
+ */
+declare function hashCaseBody(body: CaseBody): string;
+/**
+ * Parse lockfile text. `label` names the source in errors, so the caller decides
+ * whether that is a path, a URL, or something else entirely.
+ *
+ * Split from {@link readLockfile} so the CLI can route every read and write
+ * through its injected file dependencies and still share these error messages.
+ */
+declare function parseLockfile(contents: string, label: string): Lockfile;
+/** Serialize with sorted keys so the diff a reviewer sees is minimal and stable. */
+declare function serializeLockfile(lock: Lockfile): string;
+declare function readLockfile(file: string): Lockfile;
+declare function writeLockfile(file: string, lock: Lockfile): void;
+
+/**
+ * Provider-agnostic sync engine.
+ *
+ * Everything that is not a vendor API call lives here: projecting stories into
+ * case bodies, binding them to remote cases, classifying what the provider
+ * holds, building the plan, and applying it. Adapters stay thin.
+ *
+ * Two phases, deliberately separate so `--dry-run` and a real run share one code
+ * path: {@link analyzeSync} reads and decides, {@link applySync} writes.
+ *
+ * fn(args, deps) throughout.
+ */
+
+/** Which executions get their evidence uploaded. */
+type AttachPolicy = "failed" | "all" | "none";
+interface SyncEngineConfig {
+    /**
+     * Ticket-id prefix that marks a `story.tickets` entry as this provider's case
+     * id (TestRail's "C1234"). Without it, only the lockfile binds.
+     */
+    ticketPrefix?: string;
+    /**
+     * Whether the prefix is decoration to strip ("C1234" -> "1234", TestRail) or
+     * part of the id itself ("PROJ-42" stays whole, Xray/Jira). Default true.
+     */
+    ticketPrefixStrip?: boolean;
+    /** Base URL of the published HTML report, used for links back from cases. */
+    reportUrl?: string;
+    /**
+     * Turns a scenario into the fragment appended to `reportUrl`, for a link that
+     * lands on the scenario rather than the top of the page.
+     *
+     * Caller-supplied for the same reason the markdown formatter's option is
+     * (`types/options.ts`): the correct slug depends on how the docs site routes,
+     * and guessing it produces links that 404. Without it, cases link to the
+     * report page itself.
+     */
+    scenarioAnchor?: (tc: TestCaseResult) => string | undefined;
+    /** Default "failed": nobody watches a passing test's video, and quotas are real. */
+    attach?: AttachPolicy;
+    /** Similarity at or above which an unlinked case is flagged as a possible duplicate. */
+    duplicateThreshold?: number;
+}
+/** A story, ready to be a case. */
+interface LocalBehaviour {
+    fingerprint: string;
+    testCase: TestCaseResult;
+    body: CaseBody;
+}
+type CoverageClass = "automated" | "duplicated" | "possible-duplicate" | "manual-only";
+interface ClassifiedCase {
+    case: RemoteCase;
+    classification: CoverageClass;
+    /** Scenario title this case resembles or duplicates, when one was found. */
+    resembles?: string;
+    /** 0..1, present for "possible-duplicate". */
+    similarity?: number;
+}
+interface PlanCreate {
+    fingerprint: string;
+    scenario: string;
+    body: CaseBody;
 }
-interface ReportCIInfo {
-    name: string;
-    url?: string;
-    buildNumber?: string;
-    branch?: string;
-    commitSha?: string;
-    prNumber?: string;
-}
-interface ReportCoverageSummary {
-    linesPct?: number;
-    branchesPct?: number;
-    functionsPct?: number;
-    statementsPct?: number;
-}
-type ReportDocEntry = ReportDocNote | ReportDocTag | ReportDocKv | ReportDocCode | ReportDocTable | ReportDocLink | ReportDocSection | ReportDocMermaid | ReportDocScreenshot | ReportDocVideo | ReportDocHtml | ReportDocState | ReportDocCustom;
-interface ReportDocNote {
-    kind: "note";
-    text: string;
-    phase: DocPhase;
-    children?: ReportDocEntry[];
-}
-interface ReportDocTag {
-    kind: "tag";
-    names: string[];
-    phase: DocPhase;
-    children?: ReportDocEntry[];
-}
-interface ReportDocKv {
-    kind: "kv";
-    label: string;
-    value: unknown;
-    phase: DocPhase;
-    children?: ReportDocEntry[];
-}
-interface ReportDocCode {
-    kind: "code";
-    label: string;
-    content: string;
-    lang?: string;
-    phase: DocPhase;
-    children?: ReportDocEntry[];
-}
-interface ReportDocTable {
-    kind: "table";
-    label: string;
-    columns: string[];
-    rows: string[][];
-    phase: DocPhase;
-    children?: ReportDocEntry[];
-}
-interface ReportDocLink {
-    kind: "link";
-    label: string;
+interface PlanUpdate {
+    fingerprint: string;
+    caseId: string;
     url: string;
-    phase: DocPhase;
-    children?: ReportDocEntry[];
+    scenario: string;
+    body: CaseBody;
 }
-interface ReportDocSection {
-    kind: "section";
+interface PlanSkip {
+    fingerprint: string;
+    caseId: string;
+    url: string;
     title: string;
-    markdown: string;
-    phase: DocPhase;
-    children?: ReportDocEntry[];
+    reason: "remote-edited" | "case-missing";
 }
-interface ReportDocMermaid {
-    kind: "mermaid";
-    code: string;
-    title?: string;
-    phase: DocPhase;
-    children?: ReportDocEntry[];
+interface PlanOrphan {
+    fingerprint: string;
+    caseId: string;
+    url: string;
+    title: string;
 }
-interface ReportDocScreenshot {
-    kind: "screenshot";
-    path: string;
-    alt?: string;
-    phase: DocPhase;
-    children?: ReportDocEntry[];
+interface AttachmentSummary {
+    files: number;
+    bytes: number;
+    oversized: Array<{
+        filename: string;
+        bytes: number;
+        limit: number;
+    }>;
+    byRole: Record<string, number>;
+}
+interface SyncAnalysis {
+    provider: string;
+    target?: string;
+    local: LocalBehaviour[];
+    remote: ClassifiedCase[];
+    create: PlanCreate[];
+    update: PlanUpdate[];
+    unchanged: PlanUpdate[];
+    /** Human-authored cases bound via `story.tickets`. Executions only, body untouched. */
+    adopted: PlanUpdate[];
+    skipped: PlanSkip[];
+    orphaned: PlanOrphan[];
+    /** Results for behaviours already bound. Newly created cases add theirs at apply time. */
+    results: CaseResult[];
+    attachments: AttachmentSummary;
+    /** Capabilities this provider lacks that the plan would otherwise use. */
+    unsupported: string[];
+    /**
+     * Bound cases the provider would not hand back a body for, so a human edit to
+     * them cannot be detected. Reported rather than assumed safe.
+     */
+    driftUncheckable: number;
+    /** Set when the orphan count suggests the run was filtered rather than complete. */
+    partialRunWarning?: string;
+}
+interface SyncApplyResult {
+    created: Array<{
+        scenario: string;
+        caseId: string;
+        url: string;
+    }>;
+    updated: Array<{
+        scenario: string;
+        caseId: string;
+        url: string;
+    }>;
+    resultsRecorded: number;
+    resultsSkipped: Array<{
+        caseId: string;
+        reason: string;
+    }>;
+    attachmentsUploaded: number;
+    runUrl?: string;
+    errors: string[];
 }
-interface ReportDocVideo {
-    kind: "video";
-    path: string;
-    caption?: string;
-    poster?: string;
-    phase: DocPhase;
-    children?: ReportDocEntry[];
-}
-interface ReportDocHtml {
-    kind: "html";
-    /** Local HTML file path (exactly one of path/url/content) */
-    path?: string;
-    /** Remote URL rendered via iframe src (exactly one of path/url/content) */
-    url?: string;
-    /** Inline HTML content rendered via iframe srcdoc (exactly one of path/url/content) */
-    content?: string;
-    title?: string;
-    /** Iframe height: number → px, string passed through (e.g. "60vh"). Default 400px. */
-    height?: number | string;
-    phase: DocPhase;
-    children?: ReportDocEntry[];
-}
-interface ReportDocState {
-    kind: "state";
-    /** Entity name ("Basket") — diff identity across steps. Unlabeled states share one lane. */
-    label?: string;
-    /** JSON-serializable snapshot of the state at this step. */
-    value: unknown;
-    phase: DocPhase;
-    children?: ReportDocEntry[];
+/** Project one canonical test case into provider-neutral case content. */
+declare function toCaseBody(tc: TestCaseResult, config: SyncEngineConfig): CaseBody;
+/**
+ * Project a run into fingerprinted behaviours.
+ *
+ * `behaviourFingerprint` returns "" for a scenario with no steps and no
+ * `covers`, and two scenarios with identical steps collide. Both fall back to
+ * the canonical test-case id, which is unique within a run — less
+ * rename-resilient, but a stable binding beats a shared one.
+ */
+declare function projectBehaviours(run: TestRunResult, config: SyncEngineConfig): LocalBehaviour[];
+/** Attachments for one test, filtered by policy and the provider's size limit. */
+declare function collectAttachments(args: {
+    testCase: TestCaseResult;
+    policy: AttachPolicy;
+    maxBytes?: number;
+}): {
+    attachments: ResultAttachment[];
+    oversized: Array<{
+        filename: string;
+        bytes: number;
+        limit: number;
+    }>;
+};
+interface AnalyzeSyncArgs {
+    run: TestRunResult;
+    provider: SyncProvider;
+    lockfile: Lockfile;
+    config: SyncEngineConfig;
+}
+declare function analyzeSync(args: AnalyzeSyncArgs): Promise<SyncAnalysis>;
+interface ApplySyncArgs {
+    analysis: SyncAnalysis;
+    provider: SyncProvider;
+    lockfile: Lockfile;
+    config: SyncEngineConfig;
+}
+interface ApplySyncDeps {
+    logger: {
+        warn(msg: string): void;
+    };
 }
-interface ReportDocCustom {
-    kind: "custom";
-    type: string;
-    data: unknown;
-    phase: DocPhase;
-    children?: ReportDocEntry[];
+/**
+ * Execute the plan. Mutates the passed lockfile so the caller can persist it
+ * even when a later stage fails — a created case whose binding was lost would
+ * be re-created on the next run, which is the one duplicate we can actually
+ * cause.
+ */
+declare function applySync(args: ApplySyncArgs, deps: ApplySyncDeps): Promise<SyncApplyResult>;
+
+/**
+ * TestRail adapter.
+ *
+ * Translates between the sync port and TestRail's API v2. All decisions about
+ * what to write live in the engine; this file only knows how TestRail spells
+ * things.
+ *
+ * Case templates differ per instance, which is why the step and description
+ * field names are configurable. The defaults match TestRail's stock
+ * "Test Case (Steps)" template.
+ *
+ * Auth: basic, with an API key rather than a password. Generate one under
+ * My Settings -> API Keys.
+ */
+
+interface TestRailConfig {
+    /** Instance URL, e.g. https://acme.testrail.io */
+    url: string;
+    projectId: number | string;
+    /** Required on multi-suite projects. */
+    suiteId?: number | string;
+    /** Target section for created cases. Without it, creation is refused. */
+    sectionId?: number | string;
+    /** Reuse an existing run instead of creating one per sync. */
+    runId?: number | string;
+    /** Name for created runs. A UTC timestamp is appended. */
+    runName?: string;
+    /** Close the run after recording results. */
+    closeRun?: boolean;
+    /** Case template to create against, when the project uses a non-default one. */
+    templateId?: number;
+    /**
+     * Result status ids. TestRail ships 1=Passed and 5=Failed; there is no stock
+     * "skipped", so skipped results are dropped unless an id is configured.
+     */
+    statusIds?: {
+        passed?: number;
+        failed?: number;
+        skipped?: number;
+    };
+    /** Field names, for instances with customised case templates. */
+    fields?: {
+        steps?: string;
+        description?: string;
+    };
+    /**
+     * Per-file attachment limit. Conservative by default: instances have storage
+     * quotas, and a surprise 200 MB of video is a support ticket.
+     */
+    maxAttachmentBytes?: number;
+}
+interface TestRailAuth {
+    username: string;
+    apiKey: string;
+}
+declare function createTestRailProvider(config: TestRailConfig, auth: TestRailAuth, deps: AdapterDeps): SyncProvider;
+
+/**
+ * Xray (Jira Cloud) adapter.
+ *
+ * Xray splits its API in two and this adapter has to speak both: a GraphQL API
+ * for test definitions, and a REST endpoint for importing execution results.
+ * Evidence rides along with the results as base64, so screenshots and video
+ * land on the execution without a separate upload call.
+ *
+ * A case id here is a Jira issue key ("PROJ-42"), not a number, which is why
+ * `ticketPrefixStrip: false` is the right engine setting for this provider.
+ *
+ * Auth: an Xray API key pair (client id + secret) from Jira Settings -> Apps ->
+ * Xray -> API Keys. Updating an existing test's summary or description also
+ * needs Jira credentials, because those are Jira fields Xray does not own.
+ */
+
+interface XrayConfig {
+    /** Jira site URL, e.g. https://acme.atlassian.net */
+    jiraBaseUrl: string;
+    projectKey: string;
+    /** Xray Cloud API base. */
+    xrayBaseUrl?: string;
+    /** Selects the existing tests to reconcile against. */
+    jql?: string;
+    /** Xray test type for created tests. */
+    testType?: string;
+    /** Link created executions to this test plan. */
+    testPlanKey?: string;
+    /** Push results into an existing execution instead of creating one. */
+    testExecutionKey?: string;
+    /** Summary for created executions. A UTC timestamp is appended. */
+    executionSummary?: string;
+    statuses?: {
+        passed?: string;
+        failed?: string;
+        skipped?: string;
+    };
+    maxAttachmentBytes?: number;
 }
-interface ReportStep {
-    id: string;
-    index: number;
-    keyword: StepKeyword;
-    text: string;
-    status: TestStatus;
-    durationMs: number;
-    errorMessage?: string;
-    mode?: StepMode;
-    docEntries: ReportDocEntry[];
+interface XrayAuth {
+    clientId: string;
+    clientSecret: string;
+    /** Atlassian account email, needed only to update Jira summary/description. */
+    jiraEmail?: string;
+    /** Atlassian API token, needed only to update Jira summary/description. */
+    jiraToken?: string;
 }
-interface ReportScenario {
-    id: string;
-    title: string;
-    status: TestStatus;
+declare function createXrayProvider(config: XrayConfig, auth: XrayAuth, deps: AdapterDeps): SyncProvider;
+
+/**
+ * Provider registry.
+ *
+ * Adding a provider is one file next to this one plus one entry in the map
+ * below. No dynamic import: the CLI ships as a Bun single binary, which cannot
+ * see modules resolved at runtime, so adapters are in-tree by design.
+ *
+ * Credentials come from the environment only, never from the config file, so a
+ * config can be committed without leaking anything.
+ */
+
+type ProviderName = "testrail" | "xray";
+/** Per-provider config as it appears under `sync` in executable-stories.config.mjs. */
+interface SyncTargets {
+    testrail?: TestRailConfig & Partial<SyncEngineConfig>;
+    xray?: XrayConfig & Partial<SyncEngineConfig>;
+}
+interface BuiltProvider {
+    provider: SyncProvider;
+    /** Engine defaults this provider implies, overridable per target in config. */
+    engineDefaults: SyncEngineConfig;
+}
+declare const PROVIDER_NAMES: ProviderName[];
+declare function isProviderName(value: string): value is ProviderName;
+declare function buildProvider(args: {
+    name: ProviderName;
+    targets: SyncTargets;
+    env: Record<string, string | undefined>;
+}, deps: AdapterDeps): BuiltProvider;
+
+interface Formatter {
+    name: string;
+    fileExtension?: string;
+    format(run: TestRunResult): string;
+}
+interface ExecutableStoriesConfig {
+    formatters?: Record<string, Formatter>;
     /**
-     * True for scenarios authored with the framework's todo modifier
-     * (e.g. `it.todo`): specified behavior with no implementation yet.
-     * Canonical status stays "pending"; this flags why.
+     * Test-management targets for `coverage` and `sync`. Shape only — credentials
+     * are read from the environment so this file stays committable.
      */
-    planned?: boolean;
-    durationMs: number;
-    tags: string[];
-    tickets?: ReportTicket[];
-    /** Product-code paths/globs this scenario exercises (project-root-relative). */
-    covers?: string[];
-    sourceLine?: number;
-    errorMessage?: string;
-    errorStack?: string;
-    retry: number;
-    retries: number;
-    docEntries: ReportDocEntry[];
-    steps: ReportStep[];
-    attachments: ReportAttachment[];
-    /** OTel spans for the trace waterfall (carried through from the run). */
-    otelSpans?: OtelSpan[];
-}
-interface ReportFeature {
-    id: string;
-    title: string;
-    sourceFile: string;
-    summary: ReportSummary;
-    scenarios: ReportScenario[];
+    sync?: SyncTargets;
 }
-interface StoryReport {
-    schemaVersion: StoryReportSchemaVersion;
-    runId: string;
-    startedAtMs: number;
-    finishedAtMs: number;
-    durationMs: number;
-    projectRoot: string;
-    packageVersion?: string;
-    gitSha?: string;
-    ci?: ReportCIInfo;
-    coverage?: ReportCoverageSummary;
-    summary: ReportSummary;
-    features: ReportFeature[];
+
+/**
+ * Rendering for the two things a human reads: the coverage report and the plan.
+ *
+ * Coverage answers "what does my test-management system hold that my tests
+ * already cover?", which needs no write access and is the whole reason to try
+ * this. The plan borrows `terraform plan` deliberately: the idiom is already in
+ * everyone's head, and it is what makes pointing this at a company's TestRail
+ * feel safe.
+ *
+ * Pure functions of a {@link SyncAnalysis}. No IO here.
+ */
+
+interface CoverageSummary {
+    provider: string;
+    target?: string;
+    totalCases: number;
+    automated: number;
+    duplicated: number;
+    possibleDuplicate: number;
+    manualOnly: number;
+    /** Stories with no case in the provider. */
+    untracked: number;
+    /** Stories whose case was reached through a human-authored ticket id. */
+    adopted: number;
+}
+interface CoverageJson extends CoverageSummary {
+    schema: "executable-stories/sync-coverage/v1";
+    cases: Array<{
+        id: string;
+        url: string;
+        title: string;
+        section?: string;
+        classification: ClassifiedCase["classification"];
+        resembles?: string;
+        similarity?: number;
+    }>;
+    untrackedScenarios: string[];
+    orphaned: Array<{
+        caseId: string;
+        url: string;
+        title: string;
+    }>;
+    sections: Array<{
+        name: string;
+        total: number;
+        automated: number;
+    }>;
 }
-declare const STORY_REPORT_SCHEMA_VERSION: StoryReportSchemaVersion;
-declare const STORY_REPORT_SCHEMA_MAJOR: 1;
+/** Human-readable coverage, the first thing anyone sees. */
+declare function renderCoverageText(analysis: SyncAnalysis): string;
+/** The same content as Markdown, so it can be pasted, published, or PR-commented. */
+declare function renderCoverageMarkdown(analysis: SyncAnalysis): string;
+declare function buildCoverageJson(analysis: SyncAnalysis): CoverageJson;
+/** terraform-plan-shaped output. Read before anything is written. */
+declare function renderPlan(analysis: SyncAnalysis, opts: {
+    dryRun: boolean;
+}): string;
+/** What actually happened, printed after a real run. */
+declare function renderApplyResult(result: SyncApplyResult): string;
 
 /**
  * Diff types — parsed unified patches and content-anchored annotation targets.
@@ -1101,7 +1448,7 @@ interface CodeDiffScenarioRef {
     /** False = the cited scenario is not in this run — render as "unverified reference". */
     resolved: boolean;
     scenario?: string;
-    status?: TestStatus$1;
+    status?: TestStatus;
 }
 /** An annotation resolved against the parsed patch and the run. */
 interface CodeDiffAnnotation {
@@ -1135,7 +1482,7 @@ interface ReviewClaim {
     sourceFile: string;
     sourceLine: number;
     /** Test outcome. */
-    status: TestStatus$1;
+    status: TestStatus;
     /** Derived from file convention / `audience:` tag. */
     audience: ReviewAudience;
     /** Declared via `change:*` tag (defaults to `unknown`). */
@@ -1188,239 +1535,6 @@ interface ReviewResult {
     codeDiffs: CodeDiffEvidence[];
 }
 
-/**
- * Canonical executable-stories theme tokens (--es-*).
- *
- * Source of truth for the `--es-color-*`, `--es-space-*`, `--es-font-*`,
- * `--es-size-*`, `--es-radius`, `--es-line`, and `--es-measure` CSS custom
- * properties consumed by:
- *
- * - executable-stories-react (styles.css)
- * - executable-stories-formatters HTML report (CSS_STYLES, via this module)
- *
- * Consumer-side overrides on `:root` or any ancestor of the report cascade
- * through both: setting `--es-color-failed: red` on body re-colors failures
- * in both the standalone HTML report and the React component.
- *
- * The HTML formatter's pre-existing tokens (--success, --error, etc.)
- * remain in place for backward compatibility; the --es-* tokens are emitted
- * alongside them as the public override surface.
- */
-declare const ES_THEME_TOKENS_CSS: string;
-/**
- * JS-level mirror of the token values (for cases where TypeScript code needs
- * to read them — e.g., dynamic style injection or theme generators).
- */
-declare const ES_THEME_TOKEN_VALUES: {
-    readonly light: {
-        readonly "--es-color-bg": "#ffffff";
-        readonly "--es-color-fg": "#111827";
-        readonly "--es-color-muted": "#6b7280";
-        readonly "--es-color-border": "#e5e7eb";
-        readonly "--es-color-surface": "#f9fafb";
-        readonly "--es-color-link": "#2563eb";
-        readonly "--es-color-passed": "#16a34a";
-        readonly "--es-color-failed": "#dc2626";
-        readonly "--es-color-skipped": "#9ca3af";
-        readonly "--es-color-pending": "#d97706";
-    };
-    readonly dark: {
-        readonly "--es-color-bg": "#0b0f17";
-        readonly "--es-color-fg": "#e5e7eb";
-        readonly "--es-color-muted": "#9ca3af";
-        readonly "--es-color-border": "#1f2937";
-        readonly "--es-color-surface": "#111827";
-        readonly "--es-color-link": "#60a5fa";
-        readonly "--es-color-passed": "#4ade80";
-        readonly "--es-color-failed": "#f87171";
-        readonly "--es-color-skipped": "#6b7280";
-        readonly "--es-color-pending": "#fbbf24";
-    };
-};
-
-/**
- * Status mapping from raw framework statuses to canonical TestStatus.
- */
-
-/**
- * Convert a raw status to canonical TestStatus.
- *
- * @param raw - The raw status from a framework
- * @returns The canonical TestStatus
- */
-declare function normalizeStatus(raw: RawStatus): TestStatus$1;
-
-/**
- * ID generation and slug helpers for deterministic, Cucumber-compatible IDs.
- */
-/**
- * Generate a deterministic test case ID from source file and scenario name.
- *
- * @param sourceFile - The source file path
- * @param scenario - The scenario name
- * @returns A 12-character hex ID
- */
-declare function generateTestCaseId(sourceFile: string, scenario: string): string;
-/**
- * Generate a deterministic run ID from timestamp and project root.
- *
- * @param startedAtMs - Run start timestamp
- * @param projectRoot - Project root directory
- * @returns A 16-character hex ID
- */
-declare function generateRunId(startedAtMs: number, projectRoot: string): string;
-/**
- * Slugify a string for Cucumber JSON IDs.
- *
- * Converts to lowercase, replaces path separators/spaces with hyphens,
- * removes other special chars, and trims leading/trailing hyphens.
- *
- * @param text - The text to slugify
- * @returns A URL-safe slug
- */
-declare function slugify(text: string): string;
-
-/**
- * Step fallback rules for deriving step results from scenario status.
- *
- * When frameworks don't provide step-level results, we derive them
- * from the overall scenario status using these rules.
- */
-
-/**
- * Derive step results from story steps and scenario status.
- *
- * Rules:
- * - Passed: All steps are passed
- * - Skipped/Pending: All steps are skipped/pending
- * - Failed: Steps up to failure are passed, failing step is failed, rest are skipped
- *   (Heuristic: last step is the failure, or use error info if available)
- *
- * @param steps - Story steps with keywords and text
- * @param scenarioStatus - Overall scenario status
- * @param error - Optional error information to help identify failing step
- * @returns Array of step results
- */
-declare function deriveStepResults(steps: StoryStep[], scenarioStatus: TestStatus$1, error?: {
-    message?: string;
-    stack?: string;
-}): StepResult[];
-/**
- * Merge raw step events with derived step results.
- *
- * When we have partial step data from the framework, merge it with
- * the derived results, preferring actual data over derived.
- *
- * @param derived - Derived step results from fallback rules
- * @param events - Raw step events from framework (if any)
- * @returns Merged step results
- */
-declare function mergeStepResults(derived: StepResult[], events?: Array<{
-    index?: number;
-    stepId?: string;
-    status?: string;
-    durationMs?: number;
-    errorMessage?: string;
-}>): StepResult[];
-
-/**
- * Attachment resolution: embed vs link decision.
- *
- * Attachments can either be embedded inline (base64) or linked to
- * external files based on size thresholds.
- */
-
-/** Options for attachment resolution */
-interface AttachmentOptions {
-    /** Max bytes before attachment becomes external link. Default: 512KB */
-    maxEmbedBytes?: number;
-    /** Directory for external attachments */
-    externalDir?: string;
-    /** Project root for relative paths */
-    projectRoot?: string;
-}
-/**
- * Resolve a raw attachment to a canonical attachment.
- *
- * Decision logic:
- * 1. If body is already provided, use it (check size for encoding decision)
- * 2. If path is provided, read file and decide embed vs link
- * 3. For large files, return a URL reference instead of embedding
- *
- * @param raw - Raw attachment from framework
- * @param options - Resolution options
- * @returns Resolved canonical attachment
- */
-declare function resolveAttachment(raw: RawAttachment, options?: AttachmentOptions): Attachment;
-/**
- * Resolve multiple attachments.
- *
- * @param attachments - Raw attachments array
- * @param options - Resolution options
- * @returns Resolved canonical attachments
- */
-declare function resolveAttachments(attachments: RawAttachment[] | undefined, options?: AttachmentOptions): Attachment[];
-
-/**
- * Anti-Corruption Layer (ACL) - Layer 2.
- *
- * Transforms permissive RawRun data from framework adapters into
- * strict canonical TestRunResult for formatters.
- */
-
-/**
- * Canonicalize a raw run into a strict TestRunResult.
- *
- * This is the main entry point for the ACL. It:
- * - Enforces required fields with defaults
- * - Normalizes statuses to TestStatus enum
- * - Applies step fallback rules
- * - Resolves attachments (embed vs link)
- * - Generates deterministic IDs
- *
- * @param raw - Raw run data from a framework adapter
- * @param options - Canonicalization options
- * @returns Strict canonical TestRunResult
- */
-declare function canonicalizeRun(raw: RawRun, options?: CanonicalizeOptions): TestRunResult;
-
-/**
- * Validation helpers for canonical TestRunResult.
- *
- * Used in tests to verify ACL output meets all invariants.
- */
-
-/** Validation result */
-interface ValidationResult {
-    /** Whether the run is valid */
-    valid: boolean;
-    /** List of validation errors */
-    errors: string[];
-}
-/**
- * Validate a canonical TestRunResult.
- *
- * Checks:
- * - All required fields are present
- * - stepResults length matches story.steps length
- * - stepResults indexes are valid and unique
- * - Durations are non-negative
- * - Timestamps are valid
- *
- * @param run - The TestRunResult to validate
- * @returns Validation result with errors if any
- */
-declare function validateCanonicalRun(run: TestRunResult): ValidationResult;
-/**
- * Assert that a run is valid, throwing if not.
- *
- * Useful in tests.
- *
- * @param run - The TestRunResult to validate
- * @throws Error if validation fails
- */
-declare function assertValidRun(run: TestRunResult): void;
-
 /**
  * Cucumber JSON Formatter - Layer 3.
  *
@@ -1546,7 +1660,7 @@ interface ScenarioIndexItem {
      * `check-explainers` can detect drift. Status is deliberately excluded.
      */
     hash: string;
-    status: TestStatus;
+    status: TestStatus$1;
     feature: string;
     sourceFile: string;
     sourceLine?: number;
@@ -1569,13 +1683,13 @@ interface ScenarioIndexStep {
     index: number;
     keyword: ReportStep["keyword"];
     text: string;
-    status: TestStatus;
+    status: TestStatus$1;
     durationMs: number;
     errorMessage?: string;
     docKinds: string[];
 }
 interface ScenarioIndexFilters {
-    statuses?: TestStatus[];
+    statuses?: TestStatus$1[];
     tags?: string[];
     sourceFiles?: string[];
 }
@@ -1694,367 +1808,13 @@ interface WatchHandle {
  */
 declare function startWatch(options: WatchOptions, deps?: WatchDeps): WatchHandle;
 
-/**
- * Cucumber Messages types for NDJSON output.
- *
- * Minimal own types (no @cucumber/messages dependency) — consistent with
- * the project's zero-external-deps-at-runtime approach.
- *
- * Based on the Cucumber Messages protocol:
- * https://github.com/cucumber/messages
- */
-/** Protobuf-style timestamp { seconds, nanos } */
-interface Timestamp {
-    seconds: number;
-    nanos: number;
-}
-/** Protobuf-style duration { seconds, nanos } */
-interface Duration {
-    seconds: number;
-    nanos: number;
-}
-/** Location in a source file */
-interface Location {
-    line: number;
-    column?: number;
-}
-interface Meta {
-    protocolVersion: string;
-    implementation: {
-        name: string;
-        version: string;
-    };
-    runtime: {
-        name: string;
-        version: string;
-    };
-    os: {
-        name: string;
-    };
-    cpu: {
-        name: string;
-    };
-}
-interface Source {
-    uri: string;
-    data: string;
-    mediaType: "text/x.cucumber.gherkin+plain";
-}
-interface Tag {
-    location: Location;
-    name: string;
-    id: string;
-}
-type KeywordType = "Unknown" | "Context" | "Action" | "Outcome" | "Conjunction";
-interface DocString {
-    location: Location;
-    mediaType?: string;
-    content: string;
-    delimiter: string;
-}
-interface TableCell {
-    location: Location;
-    value: string;
-}
-interface TableRow {
-    location: Location;
-    cells: TableCell[];
-    id: string;
-}
-interface DataTable {
-    location: Location;
-    rows: TableRow[];
-}
-interface Step {
-    location: Location;
-    keyword: string;
-    keywordType: KeywordType;
-    text: string;
-    id: string;
-    docString?: DocString;
-    dataTable?: DataTable;
-}
-interface Scenario {
-    location: Location;
-    tags: Tag[];
-    keyword: string;
-    name: string;
-    description: string;
-    steps: Step[];
-    id: string;
-}
-interface Background {
-    location: Location;
-    keyword: string;
-    name: string;
-    description: string;
-    steps: Step[];
-    id: string;
-}
-type FeatureChild = {
-    background: Background;
-    scenario?: undefined;
-} | {
-    scenario: Scenario;
-    background?: undefined;
-};
-interface Feature {
-    location: Location;
-    tags: Tag[];
-    language: string;
-    keyword: string;
-    name: string;
-    description: string;
-    children: FeatureChild[];
-}
-interface GherkinDocument {
-    uri: string;
-    feature: Feature;
-}
-type PickleStepType = "Unknown" | "Context" | "Action" | "Outcome";
-interface PickleDocString {
-    mediaType?: string;
-    content: string;
-}
-interface PickleTableCell {
-    value: string;
-}
-interface PickleTableRow {
-    cells: PickleTableCell[];
-}
-interface PickleTable {
-    rows: PickleTableRow[];
-}
-interface PickleStepArgument {
-    docString?: PickleDocString;
-    dataTable?: PickleTable;
-}
-interface PickleStep {
-    astNodeIds: string[];
-    id: string;
-    type: PickleStepType;
-    text: string;
-    argument?: PickleStepArgument;
-}
-interface PickleTag {
-    name: string;
-    astNodeId: string;
-}
-interface Pickle {
-    id: string;
-    uri: string;
-    name: string;
-    language: string;
-    steps: PickleStep[];
-    tags: PickleTag[];
-    astNodeIds: string[];
-}
-type TestStepResultStatus = "UNKNOWN" | "PASSED" | "SKIPPED" | "PENDING" | "UNDEFINED" | "AMBIGUOUS" | "FAILED";
-interface TestStepResult {
-    duration: Duration;
-    status: TestStepResultStatus;
-    message?: string;
-}
-interface TestStep {
-    id: string;
-    pickleStepId?: string;
-    stepDefinitionIds?: string[];
-}
-interface TestCase {
-    id: string;
-    pickleId: string;
-    testSteps: TestStep[];
-}
-interface TestRunStarted {
-    timestamp: Timestamp;
-}
-interface TestCaseStarted {
-    id: string;
-    testCaseId: string;
-    timestamp: Timestamp;
-    attempt: number;
-}
-interface TestStepStarted {
-    testCaseStartedId: string;
-    testStepId: string;
-    timestamp: Timestamp;
-}
-interface TestStepFinished {
-    testCaseStartedId: string;
-    testStepId: string;
-    testStepResult: TestStepResult;
-    timestamp: Timestamp;
-}
-interface TestCaseFinished {
-    testCaseStartedId: string;
-    timestamp: Timestamp;
-    willBeRetried: boolean;
-}
-interface TestRunFinished {
-    timestamp: Timestamp;
-    success: boolean;
-}
-type AttachmentContentEncoding = "IDENTITY" | "BASE64";
-interface CucumberAttachment {
-    testCaseStartedId: string;
-    testStepId?: string;
-    body: string;
-    mediaType: string;
-    contentEncoding: AttachmentContentEncoding;
-}
-/**
- * Each NDJSON line is one Envelope with exactly one field set.
- */
-type Envelope = {
-    meta: Meta;
-} | {
-    source: Source;
-} | {
-    gherkinDocument: GherkinDocument;
-} | {
-    pickle: Pickle;
-} | {
-    testRunStarted: TestRunStarted;
-} | {
-    testCase: TestCase;
-} | {
-    testCaseStarted: TestCaseStarted;
-} | {
-    testStepStarted: TestStepStarted;
-} | {
-    testStepFinished: TestStepFinished;
-} | {
-    testCaseFinished: TestCaseFinished;
-} | {
-    testRunFinished: TestRunFinished;
-} | {
-    attachment: CucumberAttachment;
-};
-
-/**
- * Convert a canonical TestRunResult into a frozen-shape StoryReport for UI renderers.
- */
-declare function toStoryReport(run: TestRunResult): StoryReport;
-
-/**
- * NDJSON-to-TestRunResult parser.
- *
- * Parses Cucumber Messages NDJSON (one JSON envelope per line) back into
- * a TestRunResult suitable for rendering by HtmlFormatter or other formatters.
- *
- * This is the NDJSON compat path: it produces a minimal but sufficient
- * TestRunResult. Fields not present in the NDJSON stream are given
- * sensible defaults.
- */
-
-/**
- * Parse an NDJSON string into a TestRunResult.
- *
- * @param ndjson - NDJSON string (one JSON envelope per line)
- * @returns TestRunResult reconstructed from the envelopes
- */
-declare function parseNdjson(ndjson: string): TestRunResult;
-/**
- * Parse an array of Envelope objects into a TestRunResult.
- *
- * @param envelopes - Array of Cucumber Messages envelopes
- * @returns TestRunResult reconstructed from the envelopes
- */
-declare function parseEnvelopes(envelopes: Envelope[]): TestRunResult;
-
-/**
- * Session trajectory primitive — the valuable part of the old `serve.ts`.
- *
- * Pins a session baseline (the first run observed) and folds each subsequent run
- * forward, so a docs/agent loop can show "how this run compares to where the
- * session started" rather than just the noise between adjacent runs. Pure (no
- * I/O, no diff engine) so it lives in core and is consumable by the Astro
- * integration and the CLI alike. Diffing the runs is layered on top by the
- * consumer (the diff engine lives in the formatters package).
- */
-
-/**
- * The realtime state a live view renders. The session baseline is pinned to the
- * first run observed after boot, so the headline tracks the whole loop's
- * trajectory rather than the noise between any two adjacent iterations.
- */
-interface RunState {
-    /** First run observed this session — the trajectory anchor. */
-    sessionBaseline: TestRunResult | null;
-    /** The run immediately before {@link RunState.current} — the per-iteration anchor. */
-    previous: TestRunResult | null;
-    /** Latest run. */
-    current: TestRunResult | null;
-    /** How many runs have been observed since boot. */
-    runCount: number;
-}
-/** The empty state before any run has been observed. */
-declare const initialRunState: RunState;
-/**
- * Fold a freshly-read run into the prior state. The first run pins the session
- * baseline; later runs shift `previous`/`current` forward. Pure.
- */
-declare function advanceState(prev: RunState, run: TestRunResult): RunState;
-
-/**
- * Canonical builders for doc entries whose construction carries a rule worth
- * keeping in one place. Adapters import these instead of re-implementing the
- * logic (the `html` exactly-one-of-source rule was previously copied verbatim
- * across the Vitest, Jest, Cypress, and Playwright adapters).
- */
-
-/** Source/presentation options for an `html` doc entry. */
-interface HtmlDocOptions {
-    /** Local HTML file path (inlined into the report by default). */
-    path?: string;
-    /** Remote URL rendered via iframe src. */
-    url?: string;
-    /** Inline HTML content rendered via iframe srcdoc. */
-    content?: string;
-    title?: string;
-    /** Iframe height: number → px, string passed through (e.g. '60vh'). Default 400px. */
-    height?: number | string;
-}
-/**
- * Build an `html` DocEntry, enforcing that exactly one of path/url/content is
- * set. Throws otherwise — this is the single source of that rule.
- */
-declare function buildHtmlDocEntry(options: HtmlDocOptions): DocEntry;
-
-/**
- * Duration formatting utilities.
- */
-/**
- * Format milliseconds as human-readable duration.
- *
- * @param ms - Duration in milliseconds
- * @returns Formatted string (e.g., "123 ms", "1.5 s", "2m 30s")
- */
-declare function formatDuration(ms: number): string;
-/**
- * Convert milliseconds to nanoseconds.
- *
- * Used for Cucumber JSON format which expects nanoseconds.
- *
- * @param ms - Duration in milliseconds
- * @returns Duration in nanoseconds
- */
-declare function msToNanoseconds(ms: number): number;
-/**
- * Convert nanoseconds to milliseconds.
- *
- * @param ns - Duration in nanoseconds
- * @returns Duration in milliseconds
- */
-declare function nanosecondsToMs(ns: number): number;
-
 interface BehaviorDiffEntry {
     id: string;
     title: string;
     sourceFile: string;
     kind: ScenarioChangeKind;
-    baselineStatus?: TestStatus;
-    currentStatus?: TestStatus;
+    baselineStatus?: TestStatus$1;
+    currentStatus?: TestStatus$1;
 }
 interface BehaviorDiff {
     schemaVersion: "1.0";
@@ -2072,7 +1832,7 @@ interface BehaviorDiff {
  * Classify a single scenario's status transition between two runs.
  * Shares the `ScenarioChangeKind` vocabulary with the full compare engine.
  */
-declare function classifyStatusChange(baseline: TestStatus | undefined, current: TestStatus | undefined): ScenarioChangeKind;
+declare function classifyStatusChange(baseline: TestStatus$1 | undefined, current: TestStatus$1 | undefined): ScenarioChangeKind;
 /**
  * Scenario-level diff of two StoryReports, keyed by scenario id. Reports status
  * transitions (the agent triage signal), not the full field-by-field diff that
@@ -2631,27 +2391,6 @@ declare function clearVersionCache(): void;
  */
 declare function detectCI(env?: Record<string, string | undefined>): RawCIInfo | undefined;
 
-/**
- * OTel trace context detection.
- *
- * Detects an active OpenTelemetry span via `@opentelemetry/api` (optional peer).
- * Uses `createRequire` so the import is lazy and never breaks if OTel isn't installed.
- */
-interface OtelTraceContext {
-    traceId: string;
-    spanId: string;
-}
-/**
- * Try to read trace context from the currently-active OTel span.
- * Returns `undefined` when `@opentelemetry/api` is not installed or no span is active.
- */
-declare function tryGetActiveOtelContext(): OtelTraceContext | undefined;
-/**
- * Replace `{traceId}` in a URL template.
- * Returns `undefined` when no template is provided.
- */
-declare function resolveTraceUrl(template: string | undefined, traceId: string): string | undefined;
-
 /**
  * Notification orchestrator.
  *
@@ -2684,7 +2423,7 @@ interface SendNotificationsDeps {
     logger: {
         warn(msg: string): void;
     };
-    toCIInfo: (raw?: RawCIInfo) => CIInfo$1 | undefined;
+    toCIInfo: (raw?: RawCIInfo) => CIInfo | undefined;
     env?: Record<string, string | undefined>;
 }
 /**
@@ -2952,13 +2691,13 @@ declare function listScenarios(args: ListScenariosArgs, _deps: ListScenariosDeps
 interface CheckArgs {
     testCases: TestCaseResult[];
     /** Baseline scenario statuses keyed by scenario id, for regressed/fixed deltas. */
-    baseline?: Map<string, TestStatus$1>;
+    baseline?: Map<string, TestStatus>;
     format: "text" | "json";
 }
 type CheckDeps = Record<string, never>;
 /** A single rendered step inside a failing scenario. */
 interface CheckStep {
-    keyword: StepKeyword$1;
+    keyword: StepKeyword;
     text: string;
     /** True when this step is the one that failed. */
     failed: boolean;
@@ -3076,7 +2815,7 @@ interface TriageItem {
     rank: number;
     id: string;
     scenario: string;
-    status: TestStatus$1;
+    status: TestStatus;
     /** `sourceFile:sourceLine` */
     location: string;
     /** Product-code paths to fix. Empty when the scenario declared no `covers`. */
@@ -3098,7 +2837,7 @@ interface TriageReport {
 interface TriageArgs {
     testCases: TestCaseResult[];
     /** Baseline statuses by scenario id, to flag regressions and rank them first. */
-    baseline?: Map<string, TestStatus$1>;
+    baseline?: Map<string, TestStatus>;
     format: "text" | "json";
 }
 type TriageDeps = Record<string, never>;
@@ -3439,7 +3178,7 @@ interface TraceabilityRequirement {
     scenarios: Array<{
         id: string;
         title: string;
-        status: TestStatus$1;
+        status: TestStatus;
         sourceFile: string;
         sourceLine: number;
         covers: string[];
@@ -3468,7 +3207,7 @@ interface TraceabilityMatrix {
     untraced: Array<{
         id: string;
         title: string;
-        status: TestStatus$1;
+        status: TestStatus;
         sourceFile: string;
         sourceLine: number;
     }>;
@@ -3616,4 +3355,4 @@ declare function normalizeVitestResults(testModules: Parameters<typeof adaptVite
  */
 declare function normalizePlaywrightResults(testResults: Parameters<typeof adaptPlaywrightRun>[0], adapterOptions?: Parameters<typeof adaptPlaywrightRun>[1], canonicalizeOptions?: CanonicalizeOptions): TestRunResult;
 
-export { AgentTextFormatter, type AnchorResolution, type AnchorState, type AstroAssetResult, AstroFormatter, type AstroFormatterOptions as AstroFormatterOpts, Attachment, type BehaviorDebuggerIssue, type BehaviorDiff, type BehaviorDiffEntry, type BehaviorManifest, BehaviorManifestJsonFormatter, type BehaviorManifestJsonOptions, type BehaviorSourceFile, type BehaviorTag, type BundleOptions, type BundleResult, CIProvider, type CanonicalizeOptions, type ChangeType, type ChangedFile, type ChangedFileReview, type CheckArgs, type CheckDeps, type CheckFailure, type CheckReport, type CheckStep, type CodeDiffAnnotation, type CodeDiffAnnotationInput, type CodeDiffEvidence, type CodeDiffInput, type CodeDiffScenarioRef, type CodeDiffSidecar, type CodeDiffSidecarAnnotation, type ColocatedStyle, type CompareFormat, type CompareFormatterOptions, type ConfluenceAuth, ConfluenceFormatter, type ConfluenceFormatterOptions as ConfluenceFormatterOpts, type CopyMarkdownAssetsOptions, CucumberHtmlFormatter, type CucumberHtmlOptions, CucumberJsonFormatter, type CucumberJsonOptions, CucumberMessagesFormatter, type CucumberMessagesOptions, type DeploymentEntry, type DeploymentLedger, type DeploymentStatus, type DiffAnchor, type DiffHunk, type DiffLine, type DiffRunsOptions, DocEntry, DocPhase, ES_THEME_TOKENS_CSS, ES_THEME_TOKEN_VALUES, type EnvironmentDrift, type EvidenceStrength, type ExecutableStoriesConfig, type FetchFn, type FileChangeKind, type FileDiff, type FlakinessLevel, type Formatter, type FormatterOptions, type GenerateArgs, type GenerateCompareResult, type GenerateDeps, type GenerateResult, type GenericWebhookNotifierOptions, type GoalArgs, type GoalDeps, type GoalReport, type GoalRequirementResult, type HistoryEntry, type HistoryStore, type HtmlDocOptions, type IJsonDataTable, type IJsonDocString, type IJsonEmbedding, type IJsonFeature, type IJsonScenario, type IJsonStep, type IJsonStepArgument, type IJsonStepResult, type IJsonTableRow, type IJsonTag, JUnitFormatter, type JUnitOptions, type JiraAuth, type JiraPublishMode, type ListScenariosArgs, type ListScenariosDeps, type Logger, MIN_FLAKINESS_SAMPLES, MIN_METRIC_SAMPLES, MIN_PERF_SAMPLES, MarkdownFormatter, type MarkdownFormatterOptions, type MarkdownOptions, type MarkdownRenderers, NormalizedTicket, type NotificationSummary, type NotifyCondition, OtelSpan, type OtelTraceContext, type OutputConfig, type OutputFormat, type OutputMode, type OutputRule, type PerformanceTrend, type PublishConfluenceArgs, type PublishConfluenceDeps, type PublishConfluenceResult, type PublishJiraArgs, type PublishJiraDeps, type PublishJiraResult, type RatchetViolation, RawAttachment, RawCIInfo, RawRun, RawStatus, type RecordDeploymentArgs, type RecordDeploymentResult, type ReleaseManifest, ReleaseManifestFormatter, type ReportAttachment, type ReportCIInfo, type ReportCoverageSummary, type ReportDocCode, type ReportDocCustom, type ReportDocEntry, type ReportDocKv, type ReportDocLink, type ReportDocMermaid, type ReportDocNote, type ReportDocScreenshot, type ReportDocSection, type ReportDocTable, type ReportDocTag, type ReportFeature, ReportGenerator, type ReportScenario, type ReportStep, type ReportSummary, type ReportTicket, type ResolvedFormatterOptions, type ReviewAudience, type ReviewBand, type ReviewClaim, type ReviewContext, ReviewHtmlFormatter, type ReviewHtmlOptions, ReviewMarkdownFormatter, type ReviewMarkdownOptions, type ReviewResult, type ReviewSummary, RunDiffChangelogFormatter, type RunDiffChangelogOptions, RunDiffHtmlFormatter, type RunDiffHtmlOptions, RunDiffMarkdownFormatter, type RunDiffMarkdownOptions, type RunDiffResult, type RunDiffSummary, type RunState, STORY_REPORT_SCHEMA_MAJOR, STORY_REPORT_SCHEMA_VERSION, type ScenarioChangeFlags, type ScenarioChangeKind, type ScenarioDiff, type ScenarioIndex, type ScenarioIndexFilters, type ScenarioIndexItem, ScenarioIndexJsonFormatter, type ScenarioIndexJsonOptions, type ScenarioIndexStep, type ScenarioSnapshot, type SortTestCasesMode, type StabilityGrade, type StarlightBadge, StepKeyword$1 as StepKeyword, StepResult, type StoryReport, StoryReportJsonFormatter, type StoryReportJsonOptions, type StoryReportSchemaVersion, StoryStep, TestCaseResult, type TestHistory, type TestMetrics, TestRunResult, TestStatus$1 as TestStatus, TraceabilityCsvFormatter, type TraceabilityMatrix, TraceabilityMatrixFormatter, type TraceabilityRequirement, type TriageArgs, type TriageDeps, type TriageItem, type TriageReport, CIInfo$1 as TypedCIInfo, type ValidationResult, type WatchDeps, type WatchHandle, type WatchOptions, type WebhookPayload, type WebhookSignerHmac, type WriteFile, adaptJestRun, adaptPlaywrightRun, adaptVitestRun, advanceState, assembleCodeDiff, assertValidRun, buildCheck, buildGoal, buildHtmlDocEntry, buildReview, buildTriage, bundleAssets, calculateFlakiness, calculateStability, canonicalizeRun, classifyStatusChange, clearVersionCache, codeDiffDiagnostics, computeTestMetrics, copyMarkdownAssets, createAnchor, createPrCommentSummary, createReportGenerator, deriveAudience, deriveChangeType, deriveStepResults, detectCI, detectPerformanceTrend, diffRuns, diffStoryReports, findGitDir, formatDuration, generateRunComparison, generateRunId, generateTestCaseId, getDeploymentStatus, getEnvironmentDrift, gradeEvidence, hasSufficientHistory, initialRunState, isReviewableSource, isTestFile, joinNameAndExt, listScenarios, loadHistory, mergeStepResults, msToNanoseconds, nanosecondsToMs, normalizeFormats, normalizeJestResults, normalizePlaywrightResults, normalizeStatus, normalizeVitestResults, parseEnvelopes, parseNdjson, parseUnifiedDiff, publishConfluencePage, publishJiraIssue, readBranchName, readGitSha, readPackageVersion, recordDeployment, regenerateArtifacts, regenerateRun, relocateAnchor, renderCheck, renderGoal, renderTriage, resolveAttachment, resolveAttachments, resolveTraceUrl, rewriteAssetPaths, saveHistory, scenariosCoveringPaths, sendNotifications, sendSlackNotification, sendTeamsNotification, sendWebhookNotification, signBody, slugify, startWatch, stripAnsi, toAgentText, toBehaviorManifest, toReleaseManifest, toScenarioIndex, toStoryReport, toTraceabilityMatrix, tryGetActiveOtelContext, updateHistory, validateCanonicalRun };
+export { type AdapterDeps, AgentTextFormatter, type AnchorResolution, type AnchorState, type AstroAssetResult, AstroFormatter, type AstroFormatterOptions as AstroFormatterOpts, type AttachPolicy, type BehaviorDebuggerIssue, type BehaviorDiff, type BehaviorDiffEntry, type BehaviorManifest, BehaviorManifestJsonFormatter, type BehaviorManifestJsonOptions, type BehaviorSourceFile, type BehaviorTag, type BundleOptions, type BundleResult, type CaseBody, type CaseResult, type ChangeType, type ChangedFile, type ChangedFileReview, type CheckArgs, type CheckDeps, type CheckFailure, type CheckReport, type CheckStep, type CodeDiffAnnotation, type CodeDiffAnnotationInput, type CodeDiffEvidence, type CodeDiffInput, type CodeDiffScenarioRef, type CodeDiffSidecar, type CodeDiffSidecarAnnotation, type ColocatedStyle, type CompareFormat, type CompareFormatterOptions, type ConfluenceAuth, ConfluenceFormatter, type ConfluenceFormatterOptions as ConfluenceFormatterOpts, type CopyMarkdownAssetsOptions, type CoverageClass, type CoverageJson, CucumberHtmlFormatter, type CucumberHtmlOptions, CucumberJsonFormatter, type CucumberJsonOptions, CucumberMessagesFormatter, type CucumberMessagesOptions, DEFAULT_LOCKFILE_PATH, type DeploymentEntry, type DeploymentLedger, type DeploymentStatus, type DiffAnchor, type DiffHunk, type DiffLine, type DiffRunsOptions, type EnvironmentDrift, type EvidenceStrength, type ExecutableStoriesConfig, type FetchFn, type FileChangeKind, type FileDiff, type FlakinessLevel, type Formatter, type FormatterOptions, type GenerateArgs, type GenerateCompareResult, type GenerateDeps, type GenerateResult, type GenericWebhookNotifierOptions, type GoalArgs, type GoalDeps, type GoalReport, type GoalRequirementResult, type HistoryEntry, type HistoryStore, type IJsonDataTable, type IJsonDocString, type IJsonEmbedding, type IJsonFeature, type IJsonScenario, type IJsonStep, type IJsonStepArgument, type IJsonStepResult, type IJsonTableRow, type IJsonTag, JUnitFormatter, type JUnitOptions, type JiraAuth, type JiraPublishMode, type ListScenariosArgs, type ListScenariosDeps, type LockEntry, type Lockfile, type Logger, MIN_FLAKINESS_SAMPLES, MIN_METRIC_SAMPLES, MIN_PERF_SAMPLES, MarkdownFormatter, type MarkdownFormatterOptions, type MarkdownOptions, type MarkdownRenderers, type NotificationSummary, type NotifyCondition, type OutputConfig, type OutputFormat, type OutputMode, type OutputRule, PROVIDER_NAMES, type PerformanceTrend, type ProviderName, type PublishConfluenceArgs, type PublishConfluenceDeps, type PublishConfluenceResult, type PublishJiraArgs, type PublishJiraDeps, type PublishJiraResult, type RatchetViolation, type RecordDeploymentArgs, type RecordDeploymentResult, type RecordResultsSummary, type ReleaseManifest, ReleaseManifestFormatter, type RemoteCase, ReportGenerator, type ResolvedFormatterOptions, type ResultAttachment, type ReviewAudience, type ReviewBand, type ReviewClaim, type ReviewContext, ReviewHtmlFormatter, type ReviewHtmlOptions, ReviewMarkdownFormatter, type ReviewMarkdownOptions, type ReviewResult, type ReviewSummary, RunDiffChangelogFormatter, type RunDiffChangelogOptions, RunDiffHtmlFormatter, type RunDiffHtmlOptions, RunDiffMarkdownFormatter, type RunDiffMarkdownOptions, type RunDiffResult, type RunDiffSummary, type ScenarioChangeFlags, type ScenarioChangeKind, type ScenarioDiff, type ScenarioIndex, type ScenarioIndexFilters, type ScenarioIndexItem, ScenarioIndexJsonFormatter, type ScenarioIndexJsonOptions, type ScenarioIndexStep, type ScenarioSnapshot, type SortTestCasesMode, type StabilityGrade, type StarlightBadge, StoryReportJsonFormatter, type StoryReportJsonOptions, type SyncAnalysis, type SyncApplyResult, type SyncEngineConfig, type SyncProvider, type SyncTargets, type TestHistory, type TestMetrics, type TestRailConfig, TraceabilityCsvFormatter, type TraceabilityMatrix, TraceabilityMatrixFormatter, type TraceabilityRequirement, type TriageArgs, type TriageDeps, type TriageItem, type TriageReport, type WatchDeps, type WatchHandle, type WatchOptions, type WebhookPayload, type WebhookSignerHmac, type WriteFile, type XrayConfig, adaptJestRun, adaptPlaywrightRun, adaptVitestRun, analyzeSync, applySync, assembleCodeDiff, buildCheck, buildCoverageJson, buildGoal, buildProvider, buildReview, buildTriage, bundleAssets, calculateFlakiness, calculateStability, classifyStatusChange, clearVersionCache, codeDiffDiagnostics, collectAttachments, computeTestMetrics, copyMarkdownAssets, createAnchor, createPrCommentSummary, createReportGenerator, createTestRailProvider, createXrayProvider, deriveAudience, deriveChangeType, detectCI, detectPerformanceTrend, diffRuns, diffStoryReports, emptyLockfile, findGitDir, generateRunComparison, getDeploymentStatus, getEnvironmentDrift, gradeEvidence, hasSufficientHistory, hashCaseBody, isProviderName, isReviewableSource, isTestFile, joinNameAndExt, listScenarios, loadHistory, normalizeFormats, normalizeJestResults, normalizePlaywrightResults, normalizeVitestResults, parseLockfile, parseUnifiedDiff, projectBehaviours, publishConfluencePage, publishJiraIssue, readBranchName, readGitSha, readLockfile, readPackageVersion, recordDeployment, regenerateArtifacts, regenerateRun, relocateAnchor, renderApplyResult, renderCheck, renderCoverageMarkdown, renderCoverageText, renderGoal, renderPlan, renderTriage, rewriteAssetPaths, saveHistory, scenariosCoveringPaths, sendNotifications, sendSlackNotification, sendTeamsNotification, sendWebhookNotification, serializeLockfile, signBody, startWatch, stripAnsi, toAgentText, toBehaviorManifest, toCaseBody, toReleaseManifest, toScenarioIndex, toTraceabilityMatrix, updateHistory, writeLockfile };