import { E as Evidence, a as DocBridgeIndexV1, R as REFERENCE_FINDINGS_REASONS, K as KnowledgeDiagnostic, I as IndexPublication } from './knowledge-BSFT4d03.js'; import { z } from 'zod'; import { a as DocumentationStandardRuleId, D as DocBridgeConfigV1 } from './schema-CMKrwMYs.js'; /** * The retrieval index: what ranking reads. * * It is a projection of the discovery snapshot — a pure function of the snapshot, the accepted * enrichment overlay and the configuration — and nothing else. It has no scanner of its own, * which is the invariant that makes "the index" and "the snapshot" describe the same repository: * an entity retrieval can find is an entity discovery observed, with the same id, the same * content hash and the same evidence. */ declare const RETRIEVAL_INDEX_SCHEMA_VERSION: 1; declare const RetrievalKindSchema: z.ZodEnum<{ module: "module"; area: "area"; package: "package"; document: "document"; intent: "intent"; change: "change"; }>; type RetrievalKind = z.infer; /** * How much to trust a result, from most to least. * * `observed` came from code or a manifest; `declared` from a documentation declaration or the * configuration; `fuzzy` from a reference that resolved by similarity rather than by name; * `proposed` from an agent whose proposal has not been accepted. A result's confidence is the * weakest link between the entry and the relation that surfaced it. */ declare const ConfidenceSchema: z.ZodEnum<{ proposed: "proposed"; observed: "observed"; declared: "declared"; fuzzy: "fuzzy"; }>; type Confidence = z.infer; declare const AudienceSchema: z.ZodEnum<{ agent: "agent"; human: "human"; "human-and-agent": "human-and-agent"; }>; type Audience = z.infer; /** Text the lexical ranker indexes, one string per field, already bounded. */ declare const RetrievalFieldsSchema: z.ZodObject<{ title: z.ZodString; headings: z.ZodString; path: z.ZodString; symbols: z.ZodString; summary: z.ZodString; body: z.ZodString; aliases: z.ZodString; }, z.core.$strict>; type RetrievalFields = z.infer; /** One edge into or out of an entry, with the confidence of the relation it came from. */ declare const RetrievalEdgeSchema: z.ZodObject<{ kind: z.ZodString; id: z.ZodString; confidence: z.ZodEnum<{ proposed: "proposed"; observed: "observed"; declared: "declared"; fuzzy: "fuzzy"; }>; }, z.core.$strict>; type RetrievalEdge = z.infer; declare const RetrievalGraphSchema: z.ZodObject<{ pagerank: z.ZodNumber; inboundLinks: z.ZodNumber; coveredBy: z.ZodArray; mentionedBy: z.ZodArray; areaId: z.ZodOptional; packageId: z.ZodOptional; inbound: z.ZodArray; }, z.core.$strict>>; outbound: z.ZodArray; }, z.core.$strict>>; }, z.core.$strict>; type RetrievalGraph = z.infer; declare const RetrievalEntrySchema: z.ZodObject<{ id: z.ZodString; kind: z.ZodEnum<{ module: "module"; area: "area"; package: "package"; document: "document"; intent: "intent"; change: "change"; }>; path: z.ZodString; title: z.ZodString; summary: z.ZodOptional; audience: z.ZodOptional>; aliases: z.ZodArray; symbols: z.ZodOptional>; tags: z.ZodArray; fields: z.ZodObject<{ title: z.ZodString; headings: z.ZodString; path: z.ZodString; symbols: z.ZodString; summary: z.ZodString; body: z.ZodString; aliases: z.ZodString; }, z.core.$strict>; graph: z.ZodObject<{ pagerank: z.ZodNumber; inboundLinks: z.ZodNumber; coveredBy: z.ZodArray; mentionedBy: z.ZodArray; areaId: z.ZodOptional; packageId: z.ZodOptional; inbound: z.ZodArray; }, z.core.$strict>>; outbound: z.ZodArray; }, z.core.$strict>>; }, z.core.$strict>; contentHash: z.ZodString; provenance: z.ZodEnum<{ proposed: "proposed"; observed: "observed"; declared: "declared"; }>; confidence: z.ZodEnum<{ proposed: "proposed"; observed: "observed"; declared: "declared"; fuzzy: "fuzzy"; }>; ownershipId: z.ZodOptional; agentSignal: z.ZodOptional; }, z.core.$strict>; type RetrievalEntry = z.infer; declare const RetrievalIndexV1Schema: z.ZodObject<{ type: z.ZodLiteral<"retrieval-index">; schemaVersion: z.ZodLiteral<1>; contentHash: z.ZodString; contentHashAlgo: z.ZodEnum<{ "sha256-semantic-v1": "sha256-semantic-v1"; "sha256-normalized-v1": "sha256-normalized-v1"; }>; snapshotHash: z.ZodString; overlayHash: z.ZodString; configurationHash: z.ZodString; lexiconVersion: z.ZodNumber; graphMetricsVersion: z.ZodString; weights: z.ZodRecord; params: z.ZodObject<{ k1: z.ZodNumber; b: z.ZodNumber; }, z.core.$strict>; lexical: z.ZodObject<{ version: z.ZodNumber; documentCount: z.ZodNumber; fieldNames: z.ZodArray; averageFieldLength: z.ZodRecord; }, z.core.$strict>; entries: z.ZodArray; path: z.ZodString; title: z.ZodString; summary: z.ZodOptional; audience: z.ZodOptional>; aliases: z.ZodArray; symbols: z.ZodOptional>; tags: z.ZodArray; fields: z.ZodObject<{ title: z.ZodString; headings: z.ZodString; path: z.ZodString; symbols: z.ZodString; summary: z.ZodString; body: z.ZodString; aliases: z.ZodString; }, z.core.$strict>; graph: z.ZodObject<{ pagerank: z.ZodNumber; inboundLinks: z.ZodNumber; coveredBy: z.ZodArray; mentionedBy: z.ZodArray; areaId: z.ZodOptional; packageId: z.ZodOptional; inbound: z.ZodArray; }, z.core.$strict>>; outbound: z.ZodArray; }, z.core.$strict>>; }, z.core.$strict>; contentHash: z.ZodString; provenance: z.ZodEnum<{ proposed: "proposed"; observed: "observed"; declared: "declared"; }>; confidence: z.ZodEnum<{ proposed: "proposed"; observed: "observed"; declared: "declared"; fuzzy: "fuzzy"; }>; ownershipId: z.ZodOptional; agentSignal: z.ZodOptional; }, z.core.$strict>>; }, z.core.$strict>; type RetrievalIndexV1 = z.infer; /** * Accepted agent signals: bounded influence. * * An entry's signal is a share in 0..1 of this weight, and the weight is 15% of the exact-id * boost. That is the whole contract: an accepted rank hint or canonical marker can reorder * near-ties among lexical hits, and can never lift an entry past one the query named exactly. * Signals apply to lexical hits only, like every other tie-breaker. */ declare const ACCEPTED_SIGNALS_SHARE = 0.15; declare const ACCEPTED_SIGNALS_WEIGHT: number; declare const RELEVANCE_FLOOR: number; type ScoreComponents = { readonly lexical: number; readonly prior: number; readonly exactId: number; readonly exactPath: number; readonly exactSymbol: number; readonly graphProximity: number; readonly canonicality: number; /** Multiplier from the name fields: 1 when nothing in the title, headings or path matched. */ readonly aboutness: number; readonly audienceFit: number; readonly acceptedAgentSignals: number; }; type RankExplanation = { /** Query terms after the lexicon: what the ranker actually looked for. */ readonly terms: readonly string[]; /** Which terms matched in which field. */ readonly matched: Readonly>; readonly components: ScoreComponents; /** * The edge proximity found this result through. When nothing matched lexically it is the only * reason the result is here; otherwise it is what the proximity component stands on. */ readonly surfacedBy?: { readonly kind: string; readonly id: string; readonly confidence: Confidence; readonly hops: number; }; }; type RankedEntry = { readonly entry: RetrievalEntry; readonly score: number; /** * The entry's own confidence when the query matched it directly; when a relation alone * surfaced it, the weaker of the entry and that relation — a result is as trustworthy as the * least trustworthy step that produced it. */ readonly confidence: Confidence; readonly explanation: RankExplanation; }; type RankOptions = { readonly limit?: number; /** The `--agent` prior: favour documentation written for an agent. */ readonly agent?: boolean; /** Per-entry accepted overlay signals (0..1), by entry id. Overrides the `agentSignal` the projection carries. */ readonly signals?: ReadonlyMap; /** * Results scoring below this share of the best score are dropped. The default spends context * on nothing weak; a caller assembling a neighbourhood rather than an answer passes 0. */ readonly floor?: number; }; /** * Rank the projection against a query. * * Ordering is total: score descending, then an exact id match, then an ownership-backed entry, * then id ascending — so two runs agree exactly and a tie never depends on insertion order. * Results below a third of the best score are dropped: retrieval exists to spend fewer tokens. */ declare const rankRetrieval: (index: RetrievalIndexV1, term: string, options?: RankOptions) => RankedEntry[]; type SearchMatch = { /** The record kind as consumers have always read it: `ownership`, `intent`, `change`, or the entry kind. */ readonly type: string; readonly id: string; readonly path: string; readonly summary?: string; readonly score: number; /** The snapshot entity this result stands for, when it stands for one. */ readonly entityId?: string; readonly kind?: RetrievalKind; readonly provenance?: 'observed' | 'declared' | 'proposed'; readonly confidence?: Confidence; readonly evidence?: readonly Evidence[]; readonly explain?: RankExplanation; }; type SearchOptions = { /** Attach the matched terms and each scoring component to every result. Never changes the ranking. */ readonly explain?: boolean; /** The `--agent` prior. */ readonly agent?: boolean; }; /** * Search the index. * * An index that carries the retrieval projection is ranked over it — every snapshot entity, with * evidence, provenance and confidence on each result. An index built before the projection * existed is ranked the way it always was, over its `knowledge[]` and lookup records, so an older * artifact keeps answering until it is rebuilt. */ declare const searchIndex: (index: DocBridgeIndexV1, term: string, limit?: number, options?: SearchOptions) => SearchMatch[]; declare const DOCUMENTATION_STANDARD_V1_ID: "documentation-standard-v1"; declare const DOCUMENTATION_STANDARD_V1_STATUS: "stable"; type DocumentationStandardRuleLevel = 'required' | 'recommended'; type DocumentationStandardRuleStatus = 'pass' | 'fail' | 'excepted'; type DocumentationStandardEvidence = { readonly path: string; readonly detail: string; }; type DocumentationStandardRemediation = { readonly command: string; readonly detail: string; }; type DocumentationStandardRuleResult = { readonly id: DocumentationStandardRuleId; readonly level: DocumentationStandardRuleLevel; readonly status: DocumentationStandardRuleStatus; readonly ok: boolean; readonly message: string; readonly evidence: readonly DocumentationStandardEvidence[]; readonly remediation: DocumentationStandardRemediation; readonly exception?: { readonly reason: string; readonly approvedBy: string; readonly trackingUrl: string; }; }; type DocumentationConformanceReportV1 = { readonly schemaVersion: 1; readonly profile: { readonly id: typeof DOCUMENTATION_STANDARD_V1_ID; readonly version: 1; readonly status: typeof DOCUMENTATION_STANDARD_V1_STATUS; }; readonly ok: boolean; readonly recommendedOk: boolean; readonly summary: { readonly required: { readonly passed: number; readonly failed: number; readonly excepted: number; }; readonly recommended: { readonly passed: number; readonly failed: number; readonly excepted: number; }; }; readonly results: readonly DocumentationStandardRuleResult[]; }; declare const runDocumentationStandardV1: (root: string, config: DocBridgeConfigV1) => DocumentationConformanceReportV1; declare const formatDocumentationStandardText: (report: DocumentationConformanceReportV1) => string[]; /** * Splits diff findings the way the advisory does: a reference finding is pending until the change * also updates the citing documentation. `pending.length` is the advisory's `pendingCount`. */ declare const referenceFindingGroups: (findings: readonly T[]) => { all: T[]; pending: T[]; updated: T[]; }; type PendingReferenceFinding = { readonly code: string; readonly document: string; readonly line?: number; readonly target: string; readonly diagnostic: KnowledgeDiagnostic; }; /** * Why the gate failed, as a stable code. This, not free text, is what the index records: free text * can carry local paths or file bytes. */ type ReferenceFindingsReason = (typeof REFERENCE_FINDINGS_REASONS)[number]; type ReferenceFindingsFailure = { readonly ok: false; readonly reasonCode: ReferenceFindingsReason; /** A fixed sentence with no local path and no file content. */ readonly reason: string; /** The underlying error, for stderr only; never persisted. */ readonly detail?: string; readonly baseRevision?: string; readonly findings?: readonly PendingReferenceFinding[]; }; type ReferenceFindingsCheck = { readonly ok: true; readonly baseRevision: string; readonly findings: readonly PendingReferenceFinding[]; } | ReferenceFindingsFailure; /** * The publication check behind the `reference-findings` gate: snapshot the working tree, run the * advisory diff against the configured base, and count what is still pending. It fails closed — no * base, an unusable base, or a diff that cannot run or cannot be trusted is a failure, never a pass. */ declare const checkReferenceFindings: (root: string, config: DocBridgeConfigV1) => ReferenceFindingsCheck; type GateId = 'index-freshness' | 'index-reproducible' | 'human-guide-links' | 'okf-type' | 'docs-style' | 'documentation-standard-v1' | 'reference-findings'; type GateResult = { readonly id: GateId; readonly ok: boolean; readonly message: string; readonly expected?: string; readonly actual?: string; readonly details?: DocumentationConformanceReportV1; /** `reference-findings` only: the advisory `pendingCount` and every pending finding, complete. */ readonly pendingCount?: number; /** `reference-findings` only: why it failed, as a stable code (`pending` when findings are pending). */ readonly reasonCode?: ReferenceFindingsReason; readonly baseRevision?: string; readonly findings?: readonly PendingReferenceFinding[]; }; type GateRunResult = { readonly ok: boolean; readonly results: GateResult[]; }; declare const runGate: (root: string, config: DocBridgeConfigV1, id: GateId) => GateResult; /** True when the configuration selects the `reference-findings` gate. */ declare const referenceFindingsGateEnabled: (config: DocBridgeConfigV1) => boolean; type PublicationDecision = { readonly allowed: true; readonly gate?: GateResult; readonly publication?: IndexPublication; } | { readonly allowed: false; readonly gate: GateResult; }; /** * Whether `ak-docs index` may publish. Without the gate configured nothing is checked. With it, a * failing gate blocks unless the operator passed `--allow-pending-findings`, and then the index * records that it was published past the gate. */ declare const publicationDecision: (root: string, config: DocBridgeConfigV1, options?: { readonly allowPendingFindings?: boolean; }) => PublicationDecision; declare const runGates: (root: string, config: DocBridgeConfigV1, ids?: readonly GateId[]) => GateRunResult; declare const resolveGateIds: (config: DocBridgeConfigV1) => GateId[]; type IgnoredIndexEntry = { readonly path: string; /** The ignore rule that matched, as `.gitignore:12:pattern`, so the fix is one lookup away. */ readonly rule: string; }; type IndexReproducibility = { /** * Whether the question was answerable. False outside a Git checkout, when Git is unavailable, or * when the index is not tracked — in all three cases `ignored` is empty and means nothing. */ readonly checked: boolean; /** Why the check did not run, for a caller that wants to say so. */ readonly skipped?: 'no-git' | 'index-untracked'; /** Indexed paths that Git ignores, in path order. */ readonly ignored: readonly IgnoredIndexEntry[]; }; /** * The paths a committed index carries that Git ignores. * * `git check-ignore` consults the index by default, so a tracked file that also matches an ignore * pattern is correctly reported as not ignored — being committed is the whole point. A test pins * that behaviour rather than trusting it. */ declare const checkIndexReproducibility: (root: string, indexPath: string, paths: readonly string[]) => IndexReproducibility; type DoctorBadgeMetrics = { readonly handoffPct: number; readonly bridgePct: number; readonly score: number; readonly grade: DoctorReport['grade']; readonly packages: number; }; declare const doctorBadgeMetrics: (report: DoctorReport) => DoctorBadgeMetrics; declare const formatDoctorBadgeMarkdown: (metrics: DoctorBadgeMetrics) => string; declare const formatDoctorBadgeJson: (metrics: DoctorBadgeMetrics) => string; type DoctorIssue = { readonly severity: 'error' | 'warn' | 'info'; readonly code: string; readonly message: string; readonly action?: string; }; /** The share of the snapshot's documents an agent can retrieve: present in the retrieval projection. */ type DoctorReachability = { readonly documentsTotal: number; readonly documentsReachable: number; readonly unreachable: readonly string[]; readonly pct: number; }; /** * Whether the graph connects documentation to code both ways: an area with at least one document * that covers or mentions it, and a document with at least one edge into code (an area, a module * or a package it covers or mentions). `pct` is the mean of the two shares. */ type DoctorConnectivity = { readonly areasTotal: number; readonly areasDocumented: number; readonly undocumentedAreas: readonly string[]; readonly documentsTotal: number; readonly documentsLinked: number; readonly unlinkedDocuments: readonly string[]; readonly pct: number; }; type DoctorBenchmark = { readonly status: 'measured'; readonly suite: string; readonly caseCount: number; readonly hitAt1: number; readonly hitAt3: number; readonly meanReciprocalRank: number; } | { /** No golden suite, or one that could not be run: reported, never silently omitted. */ readonly status: 'not-analyzed'; readonly suite: string; readonly reason: string; }; /** Which of the three measured dimensions meet the bar an A requires, and why not when one does not. */ type DoctorGrading = { readonly reachability: boolean; readonly connectivity: boolean; readonly benchmark: boolean; readonly unmet: readonly string[]; }; type DoctorCoverage = { readonly reachability: DoctorReachability; readonly connectivity: DoctorConnectivity; readonly benchmark: DoctorBenchmark; readonly packages: { readonly total: number; readonly withAgentDoc: number; readonly withHumanDoc: number; readonly missingAgentDoc: readonly string[]; readonly missingHumanDoc: readonly string[]; }; readonly agentDocs: { readonly total: number; readonly indexed: number; readonly unindexed: readonly string[]; }; readonly freshness: { readonly ok: boolean; readonly message: string; readonly hasIndex: boolean; }; readonly gates: GateRunResult; /** Whether a clean checkout would rebuild this index, or whether generated files leak into it. */ readonly reproducibility: IndexReproducibility; }; type DoctorReport = { readonly ok: boolean; readonly score: number; readonly grade: 'A' | 'B' | 'C' | 'D' | 'F'; readonly grading: DoctorGrading; readonly coverage: DoctorCoverage; readonly badge: DoctorBadgeMetrics; readonly issues: readonly DoctorIssue[]; readonly nextActions: readonly string[]; }; declare const runDoctor: (root: string, config: DocBridgeConfigV1) => DoctorReport; declare const formatDoctorText: (report: DoctorReport) => string[]; export { referenceFindingsGateEnabled as $, ACCEPTED_SIGNALS_SHARE as A, type ReferenceFindingsCheck as B, type Confidence as C, type DoctorReport as D, type RetrievalEdge as E, RetrievalEntrySchema as F, type GateRunResult as G, type RetrievalFields as H, type IgnoredIndexEntry as I, type RetrievalGraph as J, RetrievalIndexV1Schema as K, RetrievalKindSchema as L, type ScoreComponents as M, type SearchOptions as N, checkIndexReproducibility as O, type PendingReferenceFinding as P, checkReferenceFindings as Q, type RetrievalIndexV1 as R, type SearchMatch as S, doctorBadgeMetrics as T, formatDoctorBadgeJson as U, formatDoctorBadgeMarkdown as V, formatDoctorText as W, formatDocumentationStandardText as X, publicationDecision as Y, rankRetrieval as Z, referenceFindingGroups as _, type GateResult as a, resolveGateIds as a0, runDoctor as a1, runDocumentationStandardV1 as a2, runGate as a3, runGates as a4, searchIndex as a5, type RetrievalEntry as b, type RetrievalKind as c, ACCEPTED_SIGNALS_WEIGHT as d, type Audience as e, AudienceSchema as f, ConfidenceSchema as g, DOCUMENTATION_STANDARD_V1_ID as h, DOCUMENTATION_STANDARD_V1_STATUS as i, type DoctorBadgeMetrics as j, type DoctorCoverage as k, type DoctorIssue as l, type DocumentationConformanceReportV1 as m, type DocumentationStandardEvidence as n, type DocumentationStandardRemediation as o, type DocumentationStandardRuleLevel as p, type DocumentationStandardRuleResult as q, type DocumentationStandardRuleStatus as r, type GateId as s, type IndexReproducibility as t, type PublicationDecision as u, RELEVANCE_FLOOR as v, RETRIEVAL_INDEX_SCHEMA_VERSION as w, type RankExplanation as x, type RankOptions as y, type RankedEntry as z };