semiotic 3.7.4 → 3.8.0

package/dist/components/ai/chartRecipes.d.ts

@@ -0,0 +1,278 @@
+import type { Datum } from "../charts/shared/datumTypes";
+import type { CustomLayout } from "../stream/customLayout";
+import type { GeoCustomLayout } from "../stream/geoCustomLayout";
+import type { NetworkCustomLayout } from "../stream/networkCustomLayout";
+import type { OrdinalCustomLayout } from "../stream/ordinalCustomLayout";
+import type { NavTreeNode } from "./navigationTree";
+import type { IntentId } from "./intents";
+import type { VisualizationControlDefinition } from "../controls/controlContract";
+/**
+ * A frame identifies the rendering/runtime substrate a recipe expects. It does
+ * not identify the recipe's analytical meaning — that lives in dataRoles,
+ * encodings, intents, and designContract.
+ */
+export type ChartRecipeFrameFamily = "XYFrame" | "OrdinalFrame" | "NetworkFrame" | "GeoFrame" | "XYCustomChart" | "NetworkCustomChart" | "OrdinalCustomChart" | "GeoCustomChart" | "Other";
+export type ChartRecipePortability = "portable" | "local";
+/**
+ * JSON-schema-compatible metadata for serializable recipe configuration.
+ * Kept structurally open in v0 so callers can use JSON Schema, Zod-emitted
+ * schema, or another serializable schema vocabulary without an adapter.
+ */
+export type SerializableSchema = Record<string, unknown>;
+interface RecipeDatumMarker<TDatum> {
+    /** Type-only marker; never required on a runtime layout function. */
+    readonly __chartRecipeDatumType?: TDatum;
+}
+/**
+ * Any of Semiotic's four custom-layout contracts. The datum marker preserves a
+ * recipe author's datum generic without changing the established layout APIs.
+ */
+export type CustomLayoutFunction<TDatum extends Datum = Datum, TConfig extends object = Record<string, unknown>> = (CustomLayout<TConfig> | OrdinalCustomLayout<TConfig> | NetworkCustomLayout<TConfig> | GeoCustomLayout<TConfig>) & RecipeDatumMarker<TDatum>;
+/**
+ * Serializable reference used by portable recipes. A host registry resolves
+ * the id to executable layout code; local recipes may carry the function
+ * directly instead.
+ */
+export interface RegisteredRecipeLayout {
+    id: string;
+    importPath?: string;
+    exportName?: string;
+}
+export type DataSemanticType = "nominal" | "ordinal" | "quantitative" | "temporal" | "identifier" | "boolean" | "geographic" | "unknown";
+export interface DataRoleDefinition {
+    /** Open role vocabulary: category/value, node-id, edge-source, longitude, etc. */
+    role: string;
+    /** Concrete/default field used by this recipe/example. May be omitted for computed roles. */
+    field?: string;
+    /** Recipe config key that can bind this role to a different concrete field. */
+    accessor?: string;
+    required?: boolean;
+    semanticType: DataSemanticType;
+    description?: string;
+    /** Which input collection owns the field for multi-table/network/geo recipes. */
+    source?: "data" | "nodes" | "edges" | "areas" | "points" | "lines" | string;
+}
+export type EncodingChannel = "position" | "count" | "color" | "size" | "shape" | "length" | "area" | "angle" | "connection" | "order" | "texture" | "motion" | "label" | string;
+export interface EncodingDefinition {
+    channel: EncodingChannel;
+    /** One role or a relationship among several roles. */
+    role: string | string[];
+    meaning: string;
+    /** Other channels that preserve this meaning when the primary channel fails. */
+    redundantWith?: string[];
+}
+/**
+ * String shorthand keeps v0 manifests approachable. The object form adds the
+ * rationale/strength needed by suggestion and explanation surfaces.
+ */
+export type IntentDefinition = IntentId | {
+    /** Canonical intent id. `name` is accepted as an author-friendly alias. */
+    id?: IntentId;
+    name?: IntentId;
+    strength?: "primary" | "secondary" | "supporting";
+    score?: number;
+    rationale?: string;
+};
+export interface AudienceFitDefinition {
+    audience: string;
+    fit: "strong" | "moderate" | "weak" | "avoid";
+    rationale?: string;
+}
+export interface LiteracyTargetDefinition {
+    concept: string;
+    rationale: string;
+}
+/**
+ * Example-local audience vocabulary. This mirrors the seed manifests used in
+ * the docs while audienceFit supports a compact list for ranking systems.
+ */
+export interface RecipeAudienceDefinition {
+    primary?: string;
+    familiarity?: Record<string, string | number>;
+    literacyTargets?: LiteracyTargetDefinition[];
+}
+export interface ReceptionDefinition {
+    channels: string[];
+    strengths?: string[];
+    risks?: string[];
+    scaffolds?: string[];
+    /** Whether distinct form/memorability is an intentional reception benefit. */
+    memorableForm?: boolean;
+}
+export interface DesignContractDefinition {
+    whyCustom: string;
+    /** Alias used by Intent Mark / portable manifests. */
+    whyThisForm?: string;
+    whyNotDefault?: string;
+    defaultAlternative?: string;
+    tradeoff?: string;
+    caveats?: string[];
+    misuse?: string[];
+}
+export interface RecipeStrategyContext<TDatum extends Datum = Datum, TConfig extends object = Record<string, unknown>> {
+    data: ReadonlyArray<TDatum>;
+    config: TConfig;
+    locale?: string;
+}
+export interface RecipeDescription {
+    text: string;
+    levels?: {
+        l1?: string;
+        l2?: string;
+        l3?: string;
+        l4?: string;
+    };
+}
+export type DescriptionStrategy<TDatum extends Datum = Datum, TConfig extends object = Record<string, unknown>> = (context: RecipeStrategyContext<TDatum, TConfig>) => RecipeDescription;
+export type NavigationStrategy<TDatum extends Datum = Datum, TConfig extends object = Record<string, unknown>> = (context: RecipeStrategyContext<TDatum, TConfig>) => NavTreeNode;
+/**
+ * JSON-safe navigation contract for portable recipes. Role names resolve
+ * through `dataRoles`; templates use `{field}`, `{role}`, and `{count}` tokens.
+ */
+export interface PortableNavigationStrategy {
+    groupByRole?: string;
+    groupBy?: string[];
+    itemLabelTemplate?: string;
+    summaryTemplate?: string;
+    idRole?: string;
+}
+export interface AccessibilityTableField {
+    role?: string;
+    field?: string;
+    label: string;
+    format?: "number" | "percent" | "date" | string;
+}
+export interface AccessibilityExpectations {
+    keyboardNavigation?: "required" | "recommended" | "not-applicable";
+    accessibleTable?: "required" | "recommended" | "not-applicable";
+    description?: "required" | "recommended" | "not-applicable";
+    /** The semantic unit readers should traverse instead of raw visual primitives. */
+    navigationGranularity?: "datum" | "category" | "group" | "node" | "edge" | "summary" | string;
+    dataBearingSceneNodes?: "required" | "recommended" | "not-applicable";
+    fallbackTable?: boolean;
+    redundantEncodings?: string[];
+    requirements?: string[];
+    /** Fields the scene-backed accessible table must preserve. */
+    tableFields?: AccessibilityTableField[];
+    /** Author-friendly aliases used by portable manifests. */
+    requiresTitle?: boolean;
+    requiresSummary?: boolean;
+    requiresAccessibleTable?: boolean;
+    minimumHitTarget?: number;
+    tableRoles?: string[];
+}
+export interface MobileInteractionDefinition {
+    /** Primary phone interaction, e.g. "tap", "button", "drag", "none". */
+    primary?: string;
+    /** Standard non-hover alternatives available to the reader. */
+    alternatives?: string[];
+    /** How hover detail is recovered on touch devices, e.g. "tap-to-lock". */
+    hoverFallback?: string;
+    /** Comfortable pointer target in CSS pixels. */
+    targetSize?: number;
+}
+export interface MobileLabelDefinition {
+    /** Label strategy at phone width, e.g. "direct", "inline", "external", "legend". */
+    strategy?: string;
+    /** Minimum resolved label font size in CSS pixels. */
+    minFontSize?: number;
+}
+export interface MobileCustomSemanticsDefinition {
+    /** Whether emitted scene nodes retain data semantics for audit/grounding. */
+    dataBearingSceneNodes?: boolean;
+    /** Whether emitted scene nodes use stable ids across renders. */
+    stableIds?: boolean;
+    /** Semantic unit readers should traverse on a phone. */
+    navigationGranularity?: string;
+}
+export interface MobileDesignDefinition {
+    /** Overall mobile design strategy, e.g. "responsive", "small-multiples", "summary-cards". */
+    strategy?: string;
+    /** True when the layout intentionally recomputes for narrow viewports. */
+    responsive?: boolean;
+    /** Alias for responsive, friendlier in portable manifests. */
+    supportsResponsiveLayout?: boolean;
+    /** Widths this recipe/adapter has designed variants for. */
+    breakpoints?: number[];
+    /** Minimum CSS viewport width the authored design supports. */
+    minViewportWidth?: number;
+    /** Mobile mark budget before aggregation/faceting/progressive disclosure. */
+    maxMarks?: number;
+    /** Mobile annotation budget before collapsing notes out of the plot. */
+    maxAnnotations?: number;
+    /** Minimum pointer target the recipe/adapter provides. */
+    minimumHitTarget?: number;
+    /** Whether the mobile view provides a title/summary/card before the visual. */
+    summary?: boolean | string;
+    interaction?: MobileInteractionDefinition;
+    labels?: MobileLabelDefinition;
+    custom?: MobileCustomSemanticsDefinition;
+}
+export interface RecipeAuditExpectations {
+    maxCategories?: number;
+    maxMarks?: number;
+    minimumHitTargetSize?: number;
+    requireStableIds?: boolean;
+    requireDatumCoverage?: boolean;
+    expectedSceneNodeTypes?: string[];
+    checks?: string[];
+}
+export interface RecipeExample<TDatum extends Datum = Datum, TConfig extends object = Record<string, unknown>> {
+    name: string;
+    description?: string;
+    data?: ReadonlyArray<TDatum>;
+    config?: TConfig;
+    path?: string;
+}
+export interface RecipePortabilityConfig {
+    schema: SerializableSchema;
+}
+/**
+ * Declarative identity/meaning contract for a custom chart recipe.
+ *
+ * Required v0 fields intentionally stay small. A recipe can participate before
+ * it has a schema, generated description, custom navigation tree, or detailed
+ * audit expectations; those layers can be added without changing its identity.
+ */
+export interface ChartRecipe<TDatum extends Datum = Datum, TConfig extends object = Record<string, unknown>> {
+    id: string;
+    name: string;
+    version?: string;
+    frameFamily: ChartRecipeFrameFamily;
+    portability: ChartRecipePortability;
+    layout?: CustomLayoutFunction<TDatum, TConfig> | RegisteredRecipeLayout;
+    layoutConfigSchema?: SerializableSchema;
+    portabilityConfig?: RecipePortabilityConfig;
+    dataRoles: DataRoleDefinition[];
+    encodings?: EncodingDefinition[];
+    intents: IntentDefinition[];
+    audience?: RecipeAudienceDefinition;
+    audienceFit?: AudienceFitDefinition[];
+    reception?: ReceptionDefinition;
+    designContract: DesignContractDefinition;
+    accessibility: AccessibilityExpectations;
+    /** Phone-specific contract consumed by audits, agents, and portable adapters. */
+    mobile?: MobileDesignDefinition;
+    /** Portable controls expose state semantics, never frame-specific handlers. */
+    controls?: ReadonlyArray<VisualizationControlDefinition>;
+    description?: DescriptionStrategy<TDatum, TConfig>;
+    navigation?: NavigationStrategy<TDatum, TConfig> | PortableNavigationStrategy;
+    audit?: RecipeAuditExpectations;
+    caveats?: string[];
+    examples?: RecipeExample<TDatum, TConfig>[];
+}
+/**
+ * Define a chart recipe with full generic inference. Intentionally an identity
+ * function in v0: the value is the shared, inspectable shape rather than hidden
+ * registration or runtime behavior.
+ */
+export declare function defineChartRecipe<TDatum extends Datum = Datum, TConfig extends object = Record<string, unknown>>(recipe: ChartRecipe<TDatum, TConfig>): ChartRecipe<TDatum, TConfig>;
+/**
+ * Runtime validation is intentionally limited to contract integrity. It does
+ * not try to validate a recipe's domain-specific layout configuration.
+ */
+export declare function validateChartRecipe<TDatum extends Datum = Datum, TConfig extends object = Record<string, unknown>>(recipe: ChartRecipe<TDatum, TConfig>): void;
+export declare function isRegisteredRecipeLayout(layout: unknown): layout is RegisteredRecipeLayout;
+/** True when a value can cross JSON/CLI/MCP boundaries without data loss. */
+export declare function isJsonSafe(value: unknown, seen?: Set<object>): boolean;
+export {};

package/dist/components/ai/dataPitfallsBridge.d.ts

@@ -0,0 +1,203 @@
+import type { Datum } from "../charts/shared/datumTypes";
+import { type AccessibilityAuditResult, type AuditAccessibilityOptions } from "../charts/shared/auditAccessibility";
+import { type DiagnosisResult } from "../charts/shared/diagnoseConfig";
+import { type ChartConfig, type ToConfigOptions } from "../export/chartConfig";
+import { type ChartReaderGrounding, type ChartReaderGroundingOptions } from "./readerGrounding";
+export type DataPitfallsImageMediaType = "image/png" | "image/jpeg" | "image/gif" | "image/webp";
+export interface DataPitfallsImageSource {
+    content: string;
+    mediaType: DataPitfallsImageMediaType;
+    filename?: string;
+}
+export interface DataPitfallsTextInput {
+    kind: "code" | "text";
+    content: string;
+    language?: string;
+    filename?: string;
+}
+export interface DataPitfallsImageInput {
+    kind: "image";
+    images: DataPitfallsImageSource[];
+}
+export interface DataPitfallsDocumentInput {
+    kind: "document";
+    content: string;
+    mediaType: "application/pdf";
+    filename?: string;
+}
+export interface DataPitfallsSlideContent {
+    text: string;
+    images: DataPitfallsImageSource[];
+}
+export interface DataPitfallsSlidesInput {
+    kind: "slides";
+    slides: DataPitfallsSlideContent[];
+    filename?: string;
+}
+export type DataPitfallsSingleArtifactInput = DataPitfallsTextInput | DataPitfallsImageInput | DataPitfallsDocumentInput | DataPitfallsSlidesInput;
+export interface DataPitfallsChainStage {
+    role: string;
+    artifact: DataPitfallsSingleArtifactInput;
+}
+export interface DataPitfallsChainInput {
+    kind: "chain";
+    stages: DataPitfallsChainStage[];
+}
+export interface DataPitfallsRenderedChart {
+    /** SVG markup from `semiotic/server` renderChart/renderChartWithEvidence or MCP renderChart. */
+    svg?: string;
+    /** Render evidence from `renderChartWithEvidence` or MCP renderChart. */
+    evidence?: unknown;
+    /** Optional rendered chart image for Data Pitfalls' Vision path. */
+    image?: DataPitfallsImageSource | DataPitfallsImageSource[];
+}
+export interface DataPitfallsBridgeOptions {
+    /** Default true. Include the serializable Semiotic chart config as JSON. */
+    includeConfig?: boolean;
+    /** Default true. Include JSX reconstructed from the serializable chart config. */
+    includeJSX?: boolean;
+    /** Default true. Include describeChart/buildReaderGrounding text and structure. */
+    includeGrounding?: boolean;
+    /** Default true. Include diagnoseConfig output. */
+    includeDiagnostics?: boolean;
+    /** Default true. Include auditAccessibility output. */
+    includeAccessibility?: boolean;
+    /** Optional author or app context, such as the analytical question or intended claim. */
+    context?: string;
+    /** Optional narrative/caption/claim that will be reviewed alongside the chart. */
+    narrative?: string;
+    /** Optional output from a render path. */
+    rendered?: DataPitfallsRenderedChart;
+    /** Forwarded to toConfig. Use includeData: false to omit raw rows from config/JSX stages; other stages may still summarize data. */
+    config?: ToConfigOptions;
+    /** Forwarded to buildReaderGrounding. */
+    grounding?: ChartReaderGroundingOptions;
+    /** Forwarded to auditAccessibility. */
+    accessibility?: AuditAccessibilityOptions;
+    /** Prefix used for generated filenames. Default: component name. */
+    filenamePrefix?: string;
+    /** Extra caller-supplied chain stages, appended last. */
+    additionalStages?: DataPitfallsChainStage[];
+}
+export interface DataPitfallsBridgeResult {
+    input: DataPitfallsChainInput;
+    config: ChartConfig;
+    grounding?: ChartReaderGrounding;
+    diagnosis?: DiagnosisResult;
+    accessibility?: AccessibilityAuditResult;
+}
+export type DataPitfallsSeverity = "info" | "warning" | "error" | (string & {});
+export type DataPitfallsInputKind = "text" | "code" | "image" | "document" | "slides" | "chain" | (string & {});
+export interface DataPitfallsFinding {
+    ruleId: string;
+    name: string;
+    domain: string;
+    severity: DataPitfallsSeverity;
+    evidence?: string;
+    remediation?: string;
+    explanation?: string;
+    condition?: string;
+    [key: string]: unknown;
+}
+export interface DataPitfallsReport {
+    kind: DataPitfallsInputKind;
+    findings: DataPitfallsFinding[];
+    [key: string]: unknown;
+}
+export type DataPitfallsNotificationLevel = "info" | "warning" | "error" | "neutral";
+export interface DataPitfallsChartNotification {
+    id?: string;
+    level?: DataPitfallsNotificationLevel;
+    title?: string;
+    message: string;
+    source?: string;
+    dismissible?: boolean;
+}
+export type DataPitfallsNotificationMessage = (finding: DataPitfallsFinding, index: number, report: DataPitfallsReport) => string;
+export interface DataPitfallsNotificationBridgeOptions {
+    /** Cap emitted notifications. `meta.count` keeps the uncapped finding count. */
+    max?: number;
+    /** Prefix for the source tag. Default: "datapitfalls". */
+    sourcePrefix?: string;
+    /** Passed through to ChartContainer notifications when set. */
+    dismissible?: boolean;
+    /** Custom message mapper. Defaults to remediation, explanation, evidence, then condition. */
+    message?: DataPitfallsNotificationMessage;
+}
+export interface DataPitfallsNotificationBridge {
+    notifications: DataPitfallsChartNotification[];
+    meta: {
+        count: number;
+        kind: DataPitfallsInputKind;
+    };
+}
+export type DataPitfallsAnnotationType = "label" | "text";
+export interface DataPitfallsSemioticAnnotation {
+    type: DataPitfallsAnnotationType;
+    title: string;
+    label: string;
+    wrap: number;
+    color: string;
+    className: string;
+    emphasis: "primary" | "secondary";
+    provenance: {
+        author: "datapitfalls";
+        authorKind: "watcher";
+        source: "computed";
+        basis: "llm-inference";
+        stableId: string;
+    };
+    dataPitfall: {
+        ruleId: string;
+        domain: string;
+        severity: DataPitfallsSeverity;
+        evidence: string;
+    };
+    [key: string]: unknown;
+}
+export interface DataPitfallsAnnotationBridgeOptions {
+    /** Override severity colors. Merged over the defaults. */
+    palette?: Partial<Record<string, string>>;
+    /** Cap emitted annotations. `meta.count` keeps the uncapped finding count. */
+    max?: number;
+    /** Text wrap width passed through to Semiotic v3 annotations. Default: 240. */
+    wrap?: number;
+    /** Semiotic v3 annotation type. Default: "label". */
+    type?: DataPitfallsAnnotationType;
+    /**
+     * Optional host-owned anchoring. Return `{ x, y }`, data accessors, or any
+     * other Semiotic annotation fields for findings you can position.
+     */
+    anchorFor?: (finding: DataPitfallsFinding, index: number, report: DataPitfallsReport) => Record<string, unknown> | null | undefined;
+}
+export interface DataPitfallsAnnotationBridge {
+    annotations: DataPitfallsSemioticAnnotation[];
+    meta: {
+        count: number;
+        kind: DataPitfallsInputKind;
+    };
+}
+export declare const DEFAULT_DATA_PITFALLS_ANNOTATION_PALETTE: {
+    readonly info: "#2563eb";
+    readonly warning: "#d97706";
+    readonly error: "#dc2626";
+};
+export declare function dataPitfallsFindingToNotification(finding: DataPitfallsFinding, options?: DataPitfallsNotificationBridgeOptions, index?: number, report?: DataPitfallsReport): DataPitfallsChartNotification;
+export declare function toDataPitfallsNotifications(report: DataPitfallsReport, options?: DataPitfallsNotificationBridgeOptions): DataPitfallsChartNotification[];
+export declare function buildDataPitfallsNotificationBridge(report: DataPitfallsReport, options?: DataPitfallsNotificationBridgeOptions): DataPitfallsNotificationBridge;
+export declare function dataPitfallsFindingToAnnotation(finding: DataPitfallsFinding, options?: DataPitfallsAnnotationBridgeOptions, index?: number, report?: DataPitfallsReport): DataPitfallsSemioticAnnotation;
+export declare function toDataPitfallsAnnotations(report: DataPitfallsReport, options?: DataPitfallsAnnotationBridgeOptions): DataPitfallsSemioticAnnotation[];
+export declare function buildDataPitfallsAnnotationBridge(report: DataPitfallsReport, options?: DataPitfallsAnnotationBridgeOptions): DataPitfallsAnnotationBridge;
+/**
+ * Build a Data Pitfalls-compatible chain input from a Semiotic chart config.
+ *
+ * The returned `input` is intentionally dependency-free: pass it to
+ * `detectPitfalls(input, options)` from the `datapitfalls` package in your app,
+ * CI job, or research harness. Semiotic contributes the chart config,
+ * reader-grounding payload, config diagnostics, accessibility audit, and
+ * optional rendered output; Data Pitfalls remains responsible for model-backed
+ * pitfall detection.
+ */
+export declare function buildDataPitfallsBridge(component: string, props: Datum, options?: DataPitfallsBridgeOptions): DataPitfallsBridgeResult;
+/** Convenience wrapper when you only need the Data Pitfalls input object. */
+export declare function toDataPitfallsChain(component: string, props: Datum, options?: DataPitfallsBridgeOptions): DataPitfallsChainInput;

package/dist/components/ai/dataQualityBridge.d.ts

@@ -0,0 +1,201 @@
+/**
+ * Data-quality → provenanced-annotation bridge.
+ *
+ * Ingests data-quality results — dbt source-freshness + test artifacts, Great
+ * Expectations validation results, or a normalized form anyone can hand-build —
+ * and maps them to **provenanced, lifecycled chart annotations**. A failed dbt
+ * freshness check becomes a danger threshold on the chart that says *who* found
+ * it (a system rule), *how* (a freshness rule), *when*, and against *which data
+ * snapshot* — so the chart's communicative act flips from report to alert,
+ * driven entirely by external metadata.
+ *
+ * Doctrine this module honors:
+ * - Pure, no React, no new dependencies — it shapes plain JSON into the
+ *   `Annotated[]` surface that already ships (`withProvenance` + the lifecycle
+ *   helpers do the rest).
+ * - **Read-only overlay.** It consumes a data-quality system's output and never
+ *   writes back into it. Clicking the chart does not trigger a dbt run.
+ * - **Refuse rather than mistranslate.** A check with no faithful chart
+ *   coordinate (a `not_null` test, a uniqueness expectation) is NOT given a
+ *   fabricated position — it is returned in `unplaced[]` with a reason, so the
+ *   30% an adapter can't place is announced rather than hidden.
+ *
+ * The data-quality system owns query execution, governance, and the test
+ * definitions; this bridge owns only the visual overlay and its provenance.
+ */
+import type { Datum } from "../charts/shared/datumTypes";
+import type { AnnotationAnchor, AnnotationBasis, AnnotationStatus, Annotated } from "./annotationProvenance";
+export type DataQualityStatus = "pass" | "fail" | "warn" | "error";
+/**
+ * How a check relates to a chart. Only the kinds with a clear visual analog
+ * produce an annotation; the rest are reported as `unplaced`.
+ */
+export type DataQualityCheckKind = "range" | "min" | "max" | "threshold" | "freshness" | "not-null" | "unique" | "accepted-values" | "row-condition" | "custom";
+/**
+ * A single data-quality result, normalized across source systems. The dbt and
+ * Great-Expectations parsers produce these; consumers can also hand-build them
+ * (e.g. to bridge Monte Carlo or a bespoke checker).
+ */
+export interface DataQualityResult {
+    /** Stable id of the check (test/expectation id). Becomes provenance.stableId. */
+    id: string;
+    /** Human-readable check name; falls back to id. Doubles as the provenance author. */
+    name?: string;
+    /** Concise phrase drawn on the chart. Falls back to `name`. Keep it short. */
+    label?: string;
+    status: DataQualityStatus;
+    kind: DataQualityCheckKind;
+    /** Column/field the check applies to (mapped through `fieldMap`). */
+    column?: string;
+    /** Lower bound (range/min). */
+    min?: number;
+    /** Upper bound (range/max). */
+    max?: number;
+    /** Single reference value (threshold/min/max). */
+    value?: number;
+    /** Freshness deadline or observed event time (ISO string or epoch ms). */
+    at?: string | number;
+    /** Free-form detail surfaced in the label. */
+    message?: string;
+    /** Source system. */
+    source?: "dbt" | "great-expectations" | (string & {});
+    /** Evidence type. Defaults to "rule" (deterministic constraint). */
+    basis?: AnnotationBasis;
+    /** 0–1; surfaced in the label only when < 1 (a hard rule needs no percent). */
+    confidence?: number;
+    /** ISO timestamp the check ran. */
+    createdAt?: string;
+    /** Data snapshot id (dbt invocation_id, GE run id). */
+    dataVersion?: string;
+    /** Failing-row count etc., surfaced in the label. */
+    observedCount?: number;
+}
+export interface DataQualityAnnotationOptions {
+    /** Map normalized column names → chart accessor field names. */
+    fieldMap?: Record<string, string>;
+    /** Which axis numeric thresholds map onto. Default "y". (Ranges always band on y.) */
+    valueAxis?: "x" | "y";
+    /** TTL applied to every generated annotation's lifecycle — drives freshness decay. */
+    ttlHint?: string | number;
+    /** Surface passing checks too (default false — only failures/warnings overlay). */
+    includePassed?: boolean;
+    /** Editorial status stamped on generated notes. Default "proposed". */
+    status?: AnnotationStatus;
+    /** Anchor mode. Default "semantic" so notes re-resolve through stableId on refresh. */
+    anchor?: AnnotationAnchor;
+    /** Color for failing/erroring checks. Default CSS var --semiotic-danger. */
+    failColor?: string;
+    /** Color for warnings. Default CSS var --semiotic-warning. */
+    warnColor?: string;
+    /** Color for passing checks (only used when includePassed). Default --semiotic-success. */
+    passColor?: string;
+}
+/** A result the bridge declined to place, with the reason (the D7 honesty surface). */
+export interface UnplacedDataQualityResult {
+    result: DataQualityResult;
+    reason: string;
+}
+export interface DataQualityAnnotationsResult {
+    /** Annotations ready to pass to a chart's `annotations` prop. */
+    annotations: Annotated<Datum>[];
+    /** Results with no faithful chart coordinate, each with a reason. */
+    unplaced: UnplacedDataQualityResult[];
+}
+/**
+ * Map normalized data-quality results to provenanced annotations. The pure core
+ * both the dbt and Great-Expectations parsers funnel through; call it directly
+ * to bridge any other checker.
+ */
+export declare function dataQualityToAnnotations(results: ReadonlyArray<DataQualityResult>, options?: DataQualityAnnotationOptions): DataQualityAnnotationsResult;
+/** Subset of a dbt artifact's `metadata` block we read. */
+interface DbtMetadata {
+    generated_at?: string;
+    invocation_id?: string;
+}
+/** A `sources.json` (source-freshness) result entry. */
+interface DbtFreshnessResult {
+    unique_id?: string;
+    status?: string;
+    max_loaded_at?: string;
+    snapshotted_at?: string;
+    criteria?: {
+        warn_after?: {
+            count?: number;
+            period?: string;
+        };
+        error_after?: {
+            count?: number;
+            period?: string;
+        };
+    };
+}
+/** A `run_results.json` result entry (we read the test-relevant fields). */
+interface DbtRunResult {
+    unique_id?: string;
+    status?: string;
+    failures?: number | null;
+    message?: string | null;
+}
+export interface DbtArtifacts {
+    /** Parsed `sources.json` (dbt source freshness). */
+    sources?: {
+        metadata?: DbtMetadata;
+        results?: ReadonlyArray<DbtFreshnessResult>;
+    };
+    /** Parsed `run_results.json`. */
+    runResults?: {
+        metadata?: DbtMetadata;
+        results?: ReadonlyArray<DbtRunResult>;
+    };
+}
+/**
+ * Map dbt artifacts to provenanced annotations. The strongest mapping is source
+ * freshness (`sources.json`) — a real timestamp + status becomes a time
+ * threshold. Test results (`run_results.json`) carry pass/fail but not, without
+ * `manifest.json`, the column/range semantics needed to place them; those land
+ * in `unplaced[]` with a reason (D7).
+ */
+export declare function fromDbtArtifacts(artifacts: DbtArtifacts, options?: DataQualityAnnotationOptions): DataQualityAnnotationsResult;
+interface GEExpectationConfig {
+    expectation_type?: string;
+    kwargs?: {
+        column?: string;
+        min_value?: number | null;
+        max_value?: number | null;
+        value?: number | null;
+        [key: string]: unknown;
+    };
+}
+interface GEResultEntry {
+    success?: boolean;
+    expectation_config?: GEExpectationConfig;
+    result?: {
+        observed_value?: number | string;
+        element_count?: number;
+        unexpected_count?: number;
+    };
+}
+export interface GEValidationResult {
+    success?: boolean;
+    results?: ReadonlyArray<GEResultEntry>;
+    meta?: {
+        run_id?: {
+            run_name?: string;
+            run_time?: string;
+        } | string;
+        [key: string]: unknown;
+    };
+    statistics?: {
+        evaluated_expectations?: number;
+        successful_expectations?: number;
+    };
+}
+/**
+ * Map a Great Expectations validation result to provenanced annotations.
+ * Range expectations (`expect_*_to_be_between`) become bands; single-bound
+ * expectations become thresholds. Set/uniqueness/null expectations have no
+ * single chart coordinate and are returned in `unplaced[]`. GE expectations are
+ * statistical assertions, so `basis` defaults to "statistical-test".
+ */
+export declare function fromGreatExpectations(validation: GEValidationResult, options?: DataQualityAnnotationOptions): DataQualityAnnotationsResult;
+export {};