/**
 * Shared coverage assessment and unambiguous symbol resolution.
 *
 * Code placed in `packages/core/` per Package-Boundary Check — verified
 * against AGENTS.md. These services do not invoke a language model.
 */
import type { GraphIndexAssessment, GraphIndexReferenceReport, KnowledgeCoverage, KnowledgeCoverageStatus, KnowledgeSymbolCandidate } from '@cleocode/contracts';
import { type ReferencePageRequest, type ReferencePageResult } from './assessment-projection.js';
/**
 * Read validated generation provenance without treating malformed metadata as healthy.
 *
 * T12348: this is the SUMMARY — the retained reference list is stored
 * separately and reported as `referenceCount`; read it with
 * {@link readKnowledgeIndexReferences}. A historical value with inline
 * `references` is returned as stored.
 *
 * T12474: root paths are stored relative to the project and resolved here
 * against the live project root, so a moved project reads its own paths. A
 * legacy absolute record is rebased when all its paths lie inside the project
 * root it recorded; an inconsistent one is returned as stored.
 * @param projectRoot - Explicit project root, or the ambient canonical project when omitted.
 * @returns The published assessment, or null for a legacy generation.
 * @remarks Reads only through the canonical project store. Malformed metadata throws.
 * @example
 * ```ts
 * const generation = await readKnowledgeIndexAssessment(projectRoot);
 * ```
 */
export declare function readKnowledgeIndexAssessment(projectRoot?: string): Promise<GraphIndexAssessment | null>;
/**
 * Read the published generation's retained reference list — the detail behind
 * `referenceCount` (T12348).
 *
 * This is the expensive read (hundreds of MB on a large repository), so only
 * explicit detail requests make it. A historical assessment with inline
 * `references` is honoured; a published graph with neither yields an empty list.
 * @param projectRoot - Explicit project root, or the ambient canonical project when omitted.
 * @returns Every retained reference, validated; `null` when no graph is published.
 * @example
 * ```ts
 * const references = await readKnowledgeIndexReferences(projectRoot);
 * ```
 */
export declare function readKnowledgeIndexReferences(projectRoot?: string): Promise<GraphIndexReferenceReport[] | null>;
/**
 * Read one page of the published generation's retained references, with the
 * per-kind totals of the whole list (T13330).
 *
 * The stored list is streamed: every reference is parsed to count its kind and
 * then dropped, and only the requested page is kept and fully validated. A
 * status call therefore holds one page however many references the repository
 * has — 846 151 on one 5 357-file project, over 500 MB as a single JSON value.
 * @param projectRoot - Explicit project root, or the ambient canonical project when omitted.
 * @param request - Page size, offset and optional kind filter.
 * @returns The page and totals; `null` when no graph is published.
 * @throws When the stored list is malformed or disagrees with the recorded count.
 * @example
 * ```ts
 * const result = await readKnowledgeIndexReferencePage(root, { limit: 20, offset: 0 });
 * ```
 */
export declare function readKnowledgeIndexReferencePage(projectRoot: string | undefined, request: ReferencePageRequest): Promise<ReferencePageResult | null>;
/**
 * An unresolved short name with exact identifiers the caller can choose from.
 * @remarks Consumers preserve the candidate list in their error envelope.
 * @example
 * ```ts
 * if (error instanceof KnowledgeSymbolAmbiguityError) return error.candidates;
 * ```
 */
export declare class KnowledgeSymbolAmbiguityError extends Error {
    /** Stable machine-readable failure code. */
    readonly code = "E_AMBIGUOUS_SYMBOL";
    /** Every best-matching candidate; no checkout is silently selected. */
    readonly candidates: KnowledgeSymbolCandidate[];
    /**
     * Create an ambiguity error preserving candidates for structured envelopes.
     * @param query - Unresolved short symbol name.
     * @param candidates - All equally eligible qualified identifiers.
     */
    constructor(query: string, candidates: KnowledgeSymbolCandidate[]);
}
/**
 * Resolve exact identifiers, then exact names, then partial names without choosing a tie.
 * @param query - Qualified graph identifier or symbol name.
 * @param nodes - Candidate symbols from the scoped graph.
 * @returns The unique candidate, or null if none matches.
 * @remarks Ambiguous short names throw an error carrying every eligible candidate.
 * @example
 * ```ts
 * const target = resolveKnowledgeSymbol('src/api.ts::serve', candidates);
 * ```
 */
export declare function resolveKnowledgeSymbol(query: string, nodes: readonly KnowledgeSymbolCandidate[]): KnowledgeSymbolCandidate | null;
/**
 * Add an explicit coverage limitation without hiding a prior diagnostic failure.
 * @param coverage - Assessment to update in place.
 * @param status - Newly observed coverage status.
 * @param reason - Inspectable reason supporting the status.
 * @returns Nothing; the supplied assessment retains the strongest observed defect.
 * @remarks A partial result cannot overwrite a prior missing or failed result.
 * @example
 * ```ts
 * recordKnowledgeGap(coverage, 'missing', 'No indexed symbol matches the evidence.');
 * ```
 */
export declare function recordKnowledgeGap(coverage: KnowledgeCoverage, status: KnowledgeCoverageStatus, reason: string): void;
/**
 * Assess graph coverage within the caller's maintenance budget (two seconds by default).
 *
 * Deferred work is read-only and cannot apply a repair after the response. A
 * synchronous native query cannot be preempted by JavaScript's event loop.
 * @param projectRoot - Canonical project root whose knowledge is assessed.
 * @param projectId - Existing project identity when supplied by the caller.
 * @param budgetMs - Maximum asynchronous foreground assessment time.
 * @returns Coverage with explicit reasons and a next action when deferred.
 * @remarks This service does not invoke models or mutate derived knowledge.
 * @example
 * ```ts
 * const coverage = await assessKnowledgeCoverage(projectRoot, undefined, 2000);
 * ```
 */
export declare function assessKnowledgeCoverage(projectRoot: string, projectId?: string, budgetMs?: number): Promise<KnowledgeCoverage>;
//# sourceMappingURL=knowledge.d.ts.map