import type { SourceLocator } from "./source-locator.js";
/**
 * A reference to a Sanity document used during evaluation.
 *
 * Shared between eval (producer) and studio (consumer) packages.
 * The Sanity Content Lake's `ailf.report` schema is the enforcement
 * point — both sides must agree on this shape.
 *
 * Attachable at every level of the report hierarchy:
 * - ScoreSummary.documentManifest — all docs used in the evaluation
 * - FeatureScore.documents — docs used for a specific area
 * - StoredJudgment.contextDocs (legacy alias: canonicalDocs) — docs expected for a specific task
 */
export interface DocumentRef {
    /**
     * Canonical, source-tagged retrieval contract (D0062). Optional: absent on
     * reports written before the locator landed; present and authoritative when
     * set. For `sanity-content-lake` refs the top-level `documentId`/`revision`
     * mirror the locator — treat `locator` as the source of truth when present.
     * Use {@link resolveLocator} to obtain a locator for any ref, legacy or new.
     */
    locator?: SourceLocator;
    /**
     * Sanity document ID.
     * Named `documentId` (not `_id`) because Sanity Content Lake reserves
     * underscore-prefixed field names for system fields.
     */
    documentId: string;
    /**
     * Content revision at evaluation time (enables staleness detection).
     * Named `revision` (not `_rev`) for the same Sanity reserved-name reason.
     */
    revision?: string;
    /** URL-path identifier (e.g., "groq-introduction") — leaf segment only. */
    slug: string;
    /**
     * Full URL path under `/docs/` (e.g., `content-lake/groq-introduction`).
     * Composed from the article's `primarySection->slug.current` and
     * `slug.current` via {@link buildContextDocPath}. Optional — historical
     * reports written before W0287 carry only `slug`; consumers must fall
     * back to `slug` for display when `path` is absent.
     */
    path?: string;
    /** Human-readable document title */
    title: string;
}
/**
 * Compose the canonical `/docs/`-relative path for a context-doc reference.
 *
 * Single source of truth across producers (eval doc fetcher, repo-task
 * mirroring) and consumers (dashboard projections). Resolution order:
 *
 * 1. An explicit `path` (e.g. authored on a YAML/repo-mirrored task) wins.
 * 2. Otherwise compose `sectionSlug + "/" + slug` when both are present.
 * 3. Otherwise `null` — neither caller can build a working docs URL, so
 *    consumers should disable the link rather than emit a 404.
 *
 * The leaf `slug` alone is never returned as the path because
 * `article.slug.current` is leaf-only on sanity.io/docs; the hierarchy
 * lives on `primarySection->slug.current`.
 */
export declare function buildContextDocPath(input: {
    path?: string | null;
    sectionSlug?: string | null;
    slug?: string | null;
}): string | null;
