@agentskit/doc-bridge 1.7.45 → 1.10.0

package/src/discovery/documentation.ts

@@ -1,3 +1,6 @@
+import { parseDocument, type Node as YamlNode } from 'yaml'
+import { z } from 'zod'
+
 import { contentHashForArtifactV1 } from '../index-builder/content-hash.js'
 import {
   DiscoverySnapshotV1Schema,
@@ -24,6 +27,7 @@ export type DocumentationDeclarationOptions = {
   readonly documentId?: string
   /** Agent corpus root used for conservative package/app path inference. */
   readonly agentRoot?: string
+  readonly entityLookup?: EntityLookup
 }
 
 export type DocumentationDeclarationResult = {
@@ -48,6 +52,8 @@ type RelationFields = {
   fields: Set<string>
 }
 
+type EntityLookup = ReadonlyMap<string, KnowledgeEntity>
+
 const detectionValues = new Set(['static', 'dynamic', 'external'])
 
 const evidence = (path: string, lineStart: number, lineEnd = lineStart): Evidence => ({
@@ -65,6 +71,15 @@ const diagnostic = (
   lineEnd = lineStart,
 ): DocumentationDiagnostic => ({ code, message, path: 'docbridge', evidence: evidence(path, lineStart, lineEnd) })
 
+const entityLookup = (entities: readonly KnowledgeEntity[]): EntityLookup => {
+  const lookup = new Map<string, KnowledgeEntity>()
+  for (const entity of entities) {
+    if (!lookup.has(entity.id)) lookup.set(entity.id, entity)
+    for (const alias of entity.aliases ?? []) if (!lookup.has(alias)) lookup.set(alias, entity)
+  }
+  return lookup
+}
+
 const scalar = (value: string): string => {
   const trimmed = value.trim()
   if ((trimmed.startsWith('"') && trimmed.endsWith('"')) || (trimmed.startsWith("'") && trimmed.endsWith("'"))) {
@@ -99,6 +114,71 @@ const parseListItem = (raw: string, indentation: number): string | undefined =>
   return rest.trim()
 }
 
+/*
+ * The `docbridge` block is real YAML validated by Zod.
+ *
+ * It used to be read by a hand-written parser for a YAML subset, which meant a quoted list, a
+ * multi-line string or an anchor was a syntax error in a file every other tool considered valid.
+ * The schema is deliberately structural rather than semantic: it says what shape the block has,
+ * while the checks that a relation names all four of its fields and a known detection value stay
+ * downstream, where they already produce the aggregated messages this contract promises.
+ */
+const DocbridgeRelationSchema = z
+  .object({
+    from: z.string().min(1).optional(),
+    to: z.string().min(1).optional(),
+    kind: z.string().min(1).optional(),
+    detection: z.string().min(1).optional(),
+  })
+  .strict()
+
+const DocbridgeBlockSchema = z
+  .object({
+    covers: z.array(z.string().min(1)).optional(),
+    relations: z.array(DocbridgeRelationSchema).optional(),
+  })
+  .strict()
+
+/**
+ * Map a schema issue onto the diagnostic code it has always had.
+ *
+ * The codes are a published contract — a repository may fail its build on one — so adopting a
+ * schema must not rename them. Zod says precisely what is wrong and where; this decides which
+ * existing code that corresponds to.
+ */
+const issueCode = (issue: z.core.$ZodIssue): string => {
+  const [first, second, third] = issue.path
+  if (issue.code === 'unrecognized_keys') return 'DOCBRIDGE_FIELD_UNKNOWN'
+  if (first === undefined) return 'DOCBRIDGE_BLOCK_MALFORMED'
+  if (first === 'covers') return second === undefined ? 'DOCBRIDGE_COVERS_INVALID' : 'DOCBRIDGE_REFERENCE_MISSING'
+  if (first === 'relations') {
+    if (second === undefined) return 'DOCBRIDGE_RELATIONS_INVALID'
+    return third === undefined ? 'DOCBRIDGE_RELATION_INVALID' : 'DOCBRIDGE_FIELD_UNKNOWN'
+  }
+  return 'DOCBRIDGE_STRUCTURE_INVALID'
+}
+
+const issueMessage = (issue: z.core.$ZodIssue): string => {
+  const field = issue.path.length ? `docbridge.${issue.path.join('.')}` : 'docbridge'
+  const keys = issue.code === 'unrecognized_keys' ? `: ${issue.keys.join(', ')}` : ''
+  return `${field}: ${issue.message}${keys}`
+}
+
+/** Absolute file line of an offset inside the frontmatter body. */
+const lineResolver = (body: string, frontmatterLine: number) => (offset: number): number => {
+  const safe = Math.max(0, Math.min(offset, body.length))
+  let line = frontmatterLine + 1
+  for (let index = 0; index < safe; index += 1) if (body[index] === '\n') line += 1
+  return line
+}
+
+type YamlRanged = { readonly range?: readonly [number, number, number] | null }
+
+const nodeStart = (node: unknown): number | undefined => {
+  const range = (node as YamlRanged | null | undefined)?.range
+  return range ? range[0] : undefined
+}
+
 const conventionalPackageReference = (path: string, agentRoot: string): string | undefined => {
   const prefix = `${agentRoot.replace(/\/$/, '')}/`
   if (!path.startsWith(prefix)) return undefined
@@ -139,8 +219,9 @@ const resolveEntity = (
   input: DocumentationDeclarationInput,
   lineStart: number,
   unresolved: Map<string, KnowledgeEntity>,
+  lookup: EntityLookup,
 ): KnowledgeEntity => {
-  const direct = entities.find((entity) => entity.id === reference || entity.aliases?.includes(reference))
+  const direct = lookup.get(reference)
   if (direct) return direct
   const packageReference = reference.replace(/^package:/, '')
   const packageCandidates = entities.filter((entity) => {
@@ -150,6 +231,23 @@ const resolveEntity = (
   })
   const resolved = packageCandidates.length === 1 ? packageCandidates[0] : undefined
   if (resolved) return resolved
+
+  /*
+   * An ownership id resolves to the area that carries it.
+   *
+   * Agent documents declare coverage by ownership id (`editRoot: src/query` becomes ownership
+   * `doc-bridge-query`), and until areas existed there was nothing in the graph with that
+   * identity — every such declaration became an unresolved reference, and the audit reported a
+   * documented area as a gap.
+   */
+  const ownedAreas = entities.filter((entity) => entity.kind === 'area' && entity.metadata?.ownershipId === reference)
+  if (ownedAreas.length === 1 && ownedAreas[0]) return ownedAreas[0]
+
+  // A path the repository knows an area, a module or a document by names that thing.
+  const path = reference.replace(/^\.\//, '').replace(/\/$/, '')
+  const byPath = entities.filter((entity) => (entity.kind === 'area' || entity.kind === 'module' || entity.kind === 'document') && entity.path === path)
+  if (byPath.length === 1 && byPath[0]) return byPath[0]
+
   const id = `unresolved:${reference}`
   const existing = unresolved.get(id)
   if (existing) return existing
@@ -166,6 +264,91 @@ const resolveEntity = (
 
 const relationKey = (from: string, to: string, kind: string): string => `${from}\u0000${to}\u0000${kind}`
 
+/**
+ * Read the `docbridge` block as YAML.
+ *
+ * Returns `undefined` when YAML cannot read the block at all — a tab in the indentation, a
+ * duplicate key, a scalar where a mapping was opened. The lenient line scanner below then takes
+ * over, because on a mangled block a per-line diagnostic is more use to the author than a single
+ * parser error, and because those diagnostics are the published contract.
+ */
+const parseDocbridgeYaml = (
+  input: DocumentationDeclarationInput,
+  lines: readonly string[],
+  end: number,
+):
+  | {
+      readonly covers: readonly { value: string; line: number }[]
+      readonly relations: readonly RelationFields[]
+      readonly diagnostics: readonly DocumentationDiagnostic[]
+    }
+  | undefined => {
+  const body = lines.slice(1, end).join('\n')
+  const document = parseDocument(body, { prettyErrors: false })
+  if (document.errors.length) return undefined
+
+  let data: unknown
+  try {
+    data = document.toJS()
+  } catch {
+    return undefined
+  }
+  if (typeof data !== 'object' || data === null || Array.isArray(data)) return undefined
+  const raw = (data as Record<string, unknown>).docbridge
+  const lineAt = lineResolver(body, 1)
+  const blockNode = document.get('docbridge', true) as YamlNode | undefined
+
+  const diagnostics: DocumentationDiagnostic[] = []
+  // `docbridge:` with nothing under it is empty, not malformed: DOCBRIDGE_CONTENT_MISSING says so
+  // downstream, and two diagnostics for one mistake is one too many.
+  if (raw === null || raw === undefined) return { covers: [], relations: [], diagnostics }
+
+  const parsed = DocbridgeBlockSchema.safeParse(raw)
+  if (!parsed.success) {
+    for (const issue of parsed.error.issues) {
+      const node = issue.path.length ? (document.getIn(['docbridge', ...issue.path], true) as YamlNode | undefined) : blockNode
+      diagnostics.push(diagnostic(input.path, issueCode(issue), issueMessage(issue), lineAt(nodeStart(node) ?? nodeStart(blockNode) ?? 0)))
+    }
+  }
+
+  /*
+   * Keep what is individually valid. One unknown key should not discard the declarations around
+   * it: the author gets the precise error and the graph still gets the edges they did declare.
+   */
+  const covers: { value: string; line: number }[] = []
+  const relations: RelationFields[] = []
+  // `raw` is neither null nor undefined here: the early return above settled that.
+  const record = typeof raw === 'object' && !Array.isArray(raw) ? (raw as Record<string, unknown>) : undefined
+
+  if (Array.isArray(record?.covers)) {
+    for (const [index, entry] of record.covers.entries()) {
+      if (typeof entry !== 'string' || !entry.trim()) continue
+      const node = document.getIn(['docbridge', 'covers', index], true) as YamlNode | undefined
+      covers.push({ value: entry.trim(), line: lineAt(nodeStart(node) ?? nodeStart(blockNode) ?? 0) })
+    }
+  }
+
+  if (Array.isArray(record?.relations)) {
+    for (const [index, entry] of record.relations.entries()) {
+      if (typeof entry !== 'object' || entry === null || Array.isArray(entry)) continue
+      const node = document.getIn(['docbridge', 'relations', index], true) as YamlNode | undefined
+      const startLine = lineAt(nodeStart(node) ?? nodeStart(blockNode) ?? 0)
+      const relation: RelationFields = { startLine, endLine: startLine, fields: new Set() }
+      for (const field of ['from', 'to', 'kind', 'detection'] as const) {
+        const value = (entry as Record<string, unknown>)[field]
+        if (typeof value !== 'string' || !value.trim()) continue
+        relation.fields.add(field)
+        relation[field] = value.trim()
+        const valueNode = document.getIn(['docbridge', 'relations', index, field], true) as YamlNode | undefined
+        relation.endLine = Math.max(relation.endLine, lineAt(nodeStart(valueNode) ?? nodeStart(node) ?? 0))
+      }
+      relations.push(relation)
+    }
+  }
+
+  return { covers, relations, diagnostics }
+}
+
 const parseBlock = (
   input: DocumentationDeclarationInput,
   options: Pick<DocumentationDeclarationOptions, 'agentRoot'> = {},
@@ -192,21 +375,42 @@ const parseBlock = (
   let typeLine = -1
   let packageLine = -1
   let humanDocLine = -1
+  let editRootLine = -1
+  let idLine = -1
   for (let index = 1; index < end; index += 1) {
     const line = lines[index] ?? ''
     if (docbridgeLine < 0 && /^docbridge\s*:/.test(line)) docbridgeLine = index
     if (typeLine < 0 && /^type\s*:/.test(line)) typeLine = index
     if (packageLine < 0 && /^package\s*:/.test(line)) packageLine = index
     if (humanDocLine < 0 && /^humanDoc\s*:/.test(line)) humanDocLine = index
+    if (editRootLine < 0 && /^editRoot\s*:/.test(line)) editRootLine = index
+    if (idLine < 0 && /^id\s*:/.test(line)) idLine = index
   }
   if (docbridgeLine < 0) {
     const type = typeLine >= 0 ? scalar(lines[typeLine]?.slice('type:'.length) ?? '') : ''
     const packageReference = packageLine >= 0 ? scalar(lines[packageLine]?.slice('package:'.length) ?? '') : conventionalPath ?? ''
     if (type === 'package' && packageReference) return { covers: [{ value: packageReference, line: packageLine >= 0 ? packageLine + 1 : typeLine + 1 }], relations: [], diagnostics: [], hasDocbridge: true }
     if (conventionalPath) return { covers: [{ value: packageReference, line: humanDocLine >= 0 ? humanDocLine + 1 : 1 }], relations: [], diagnostics: [], hasDocbridge: true }
+
+    /*
+     * `id` plus `editRoot` is a coverage declaration.
+     *
+     * The corpus already uses this pair to own a directory — it is what fills the ownership map
+     * and the handoff — but discovery never read it, so the graph had no edge from the sidecar to
+     * the unit it owns. With areas in the graph the reference resolves, and a documented area
+     * stops being reported as a gap.
+     */
+    const editRoot = editRootLine >= 0 ? scalar(lines[editRootLine]?.slice('editRoot:'.length) ?? '') : ''
+    const identifier = idLine >= 0 ? scalar(lines[idLine]?.slice('id:'.length) ?? '') : ''
+    if (editRoot && identifier) {
+      return { covers: [{ value: identifier, line: editRootLine + 1 }], relations: [], diagnostics: [], hasDocbridge: true }
+    }
     return { covers: [], relations: [], diagnostics: [], hasDocbridge: false }
   }
 
+  const fromYaml = parseDocbridgeYaml(input, lines, end)
+  if (fromYaml) return { ...fromYaml, hasDocbridge: true }
+
   const diagnostics: DocumentationDiagnostic[] = []
   const covers: { value: string; line: number }[] = []
   const relations: RelationFields[] = []
@@ -304,13 +508,14 @@ export const parseDocumentationDeclarations = (
   const relations: KnowledgeRelation[] = []
   const documentId = options.documentId ?? `document:${input.path}`
   const relationClaims = new Map<string, string>()
+  const lookup = options.entityLookup ?? entityLookup(options.snapshot.entities)
 
   if (!parsed.covers.length && !parsed.relations.length) {
     addDiagnostic(diagnostics, input, 'DOCBRIDGE_CONTENT_MISSING', 'docbridge must declare covers or relations.', 1)
   }
 
   for (const [index, cover] of parsed.covers.entries()) {
-    const target = resolveEntity(cover.value, options.snapshot.entities, input, cover.line, unresolved)
+    const target = resolveEntity(cover.value, options.snapshot.entities, input, cover.line, unresolved, lookup)
     relations.push({
       id: `relation:declared:${input.path}:covers:${index}`,
       kind: 'covers',
@@ -336,8 +541,8 @@ export const parseDocumentationDeclarations = (
       addDiagnostic(diagnostics, input, 'DOCBRIDGE_DETECTION_INVALID', `Invalid relation detection: ${detection}.`, declaration.startLine, declaration.endLine)
       continue
     }
-    const fromEntity = resolveEntity(from, options.snapshot.entities, input, declaration.startLine, unresolved)
-    const toEntity = resolveEntity(to, options.snapshot.entities, input, declaration.startLine, unresolved)
+    const fromEntity = resolveEntity(from, options.snapshot.entities, input, declaration.startLine, unresolved, lookup)
+    const toEntity = resolveEntity(to, options.snapshot.entities, input, declaration.startLine, unresolved, lookup)
     const key = relationKey(fromEntity.id, toEntity.id, kind)
     const previousDetection = relationClaims.get(key)
     if (previousDetection === detection) addDiagnostic(diagnostics, input, 'DOCBRIDGE_DECLARATION_DUPLICATE', 'Duplicate relation declaration.', declaration.startLine, declaration.endLine)
@@ -371,9 +576,10 @@ export const applyDocumentationDeclarations = (
   const entities = new Map(snapshot.entities.map((entity) => [entity.id, entity]))
   const relations = new Map(snapshot.relations.map((relation) => [relation.id, relation]))
   const diagnostics: DocumentationDiagnostic[] = []
+  const lookup = entityLookup(snapshot.entities)
 
   for (const document of documents) {
-    const result = parseDocumentationDeclarations(document, { snapshot, ...options })
+    const result = parseDocumentationDeclarations(document, { snapshot, ...options, entityLookup: lookup })
     diagnostics.push(...result.diagnostics)
     for (const entity of result.entities) entities.set(entity.id, entity)
     for (const relation of result.relations) relations.set(relation.id, relation)

package/src/discovery/identity.ts

@@ -0,0 +1,24 @@
+import { sha256NormalizedV1 } from '../index-builder/content-hash.js'
+
+/**
+ * Entity and relation identity, in one place.
+ *
+ * Every analyzer and every projection has to agree on what a module or a document is called, or
+ * the graph silently grows two nodes for one file and nothing joins. The hash suffix keeps a very
+ * long path addressable without exceeding the schema's identifier bound.
+ */
+
+const MAX_ID_LENGTH = 256
+const ID_HASH_LENGTH = 32
+
+export const entityId = (kind: string, value: string): string => {
+  const fullId = `${kind}:${value}`
+  if (fullId.length <= MAX_ID_LENGTH) return fullId
+
+  const suffix = `:${sha256NormalizedV1(fullId).slice(0, ID_HASH_LENGTH)}`
+  return `${fullId.slice(0, MAX_ID_LENGTH - suffix.length)}${suffix}`
+}
+
+/** Identity of an observed relation: its endpoints and kind, plus an optional discriminator. */
+export const relationId = (from: string, kind: string, to: string, discriminator?: string): string =>
+  entityId('relation', discriminator ? `${from}:${kind}:${to}:${discriminator}` : `${from}:${kind}:${to}`)

package/src/discovery/incremental.ts

@@ -0,0 +1,314 @@
+import { sha256NormalizedV1 } from '../index-builder/content-hash.js'
+import type { DiscoverySnapshotV1, Coverage, KnowledgeEntity, KnowledgeRelation } from '../schemas/knowledge.js'
+
+/**
+ * Reusing what has not changed.
+ *
+ * `EvidenceSchema.contentHash` has always existed and discovery never filled it, so every cache
+ * and every overlay could only be keyed on "the whole repository changed" — true between any two
+ * commits, and therefore useless. With a hash per file-backed entity, a second scan can tell which
+ * files it has already read and skip the expensive part: the TypeScript parse and the Markdown
+ * parse, which is where nearly all of discovery's time goes.
+ *
+ * Reuse is only sound when the answer cannot have changed, and two different things can change it:
+ *
+ * - An entity's own fields depend on its own bytes alone, so a hash match is enough to reuse it.
+ * - A relation depends on what else exists. A module importing `./new.js` resolved to nothing
+ *   before that file was added and resolves to a module after; a document mentioning `src/new.ts`
+ *   gains an edge the moment the module appears. So relation reuse also requires that the universe
+ *   the references resolve against is identical, which is what the fingerprints below capture.
+ *
+ * The consequence is that a fast run and a cold run produce the same snapshot, byte for byte, or
+ * the fast run does not happen. A cache that is only usually right is worse than no cache.
+ */
+
+export const fileContentHash = (text: string): string => sha256NormalizedV1(text)
+
+/** Kinds whose entity is one file, and therefore hashable. */
+export const FILE_BACKED_KINDS = ['module', 'document', 'package'] as const
+
+export type PriorFile = {
+  readonly entity: KnowledgeEntity
+  readonly contentHash: string
+  /** Relations this entity is the source of. */
+  readonly outgoing: readonly KnowledgeRelation[]
+  /** Coverage entries scoped to this file. */
+  readonly coverage: readonly Coverage[]
+}
+
+/** What a caller may hand back from a previous scan. */
+export type PreviousSnapshot = Pick<DiscoverySnapshotV1, 'entities' | 'relations' | 'coverage'> &
+  Partial<Pick<DiscoverySnapshotV1, 'pipelineVersion' | 'analyzerVersions' | 'configurationHash'>>
+
+/**
+ * Whether a previous snapshot may be reused at all, and why not when it may not.
+ *
+ * A hash says a file has not changed; it says nothing about whether *this* code would still read
+ * it the same way. An analyzer that learned to record a document's headings produces different
+ * entities from identical bytes, and a configuration change moves area boundaries and
+ * runtime-wiring detection. So the snapshot has to have been produced by this pipeline, these
+ * analyzers and this configuration — and a snapshot that does not say which is not trusted, since
+ * the alternative is trusting a caller's hand-assembled input with a repository scan.
+ */
+export const reuseRefusal = (
+  previous: PreviousSnapshot,
+  current: Pick<DiscoverySnapshotV1, 'pipelineVersion' | 'analyzerVersions' | 'configurationHash'>,
+): string | undefined => {
+  if (!previous.pipelineVersion || !previous.analyzerVersions || !previous.configurationHash) {
+    return 'the previous snapshot does not declare the pipeline, analyzers and configuration it was produced by'
+  }
+  if (previous.pipelineVersion !== current.pipelineVersion) {
+    return `the previous snapshot was produced by pipeline ${previous.pipelineVersion}, not ${current.pipelineVersion}`
+  }
+  if (sha256NormalizedV1(previous.analyzerVersions) !== sha256NormalizedV1(current.analyzerVersions)) {
+    return 'an analyzer version changed, so identical bytes would not produce identical entities'
+  }
+  if (previous.configurationHash !== current.configurationHash) return 'the configuration changed'
+  return undefined
+}
+
+export type PriorSnapshot = {
+  readonly modules: ReadonlyMap<string, PriorFile>
+  readonly documents: ReadonlyMap<string, PriorFile>
+  readonly moduleUniverse: string
+  readonly resolution: string
+  /** Every entity by id, for re-adding an endpoint a reused relation still points at. */
+  readonly entities: ReadonlyMap<string, KnowledgeEntity>
+}
+
+const hashOf = (entity: KnowledgeEntity): string | undefined => entity.evidence[0]?.contentHash
+
+/** Coverage scopes that belong to a single module, by the topic they start with. */
+const MODULE_COVERAGE_PREFIXES = ['dynamic-imports:', 'runtime-wiring:'] as const
+/** Coverage scopes that belong to a single document. */
+const DOCUMENT_COVERAGE_PREFIXES = ['relations:', 'mentions-symbol:'] as const
+
+const stringList = (value: unknown): readonly string[] =>
+  Array.isArray(value) ? value.filter((item): item is string => typeof item === 'string') : []
+
+/**
+ * Which names a module declares itself, as opposed to forwarding from somewhere else.
+ *
+ * The distinction decides where a documented symbol resolves to, and it is only visible in the
+ * syntax tree — so a module that skipped its parse has to read it back from what the previous scan
+ * recorded. `exports` minus `reexports` is that record.
+ */
+export const declaredExportsOf = (entity: KnowledgeEntity): readonly string[] => {
+  const exports = stringList(entity.metadata?.exports)
+  const reexports = new Set(stringList(entity.metadata?.reexports))
+  return exports.filter((name) => !reexports.has(name))
+}
+
+export const exportsOf = (entity: KnowledgeEntity): readonly string[] => stringList(entity.metadata?.exports)
+
+/**
+ * What a module's references resolve against: the module paths, the packages, and the compiler
+ * options that decide how a specifier becomes a path. A change to any of them can turn an
+ * unresolved import into a relation, so it invalidates relation reuse for every module.
+ */
+export const moduleUniverseFingerprint = (input: {
+  readonly modulePaths: readonly string[]
+  readonly packages: readonly { readonly id: string; readonly path: string; readonly name?: string }[]
+  readonly compilerOptions: unknown
+}): string =>
+  sha256NormalizedV1({
+    modules: [...input.modulePaths].sort(),
+    packages: [...input.packages].map(({ id, path, name }) => ({ id, path, ...(name ? { name } : {}) })).sort((a, b) => a.id.localeCompare(b.id)),
+    compilerOptions: input.compilerOptions,
+  })
+
+/**
+ * What a document's references resolve against: everything a module resolves against, plus the
+ * documents, the areas, the package names and which module declares each exported symbol.
+ */
+export const resolutionFingerprint = (input: {
+  readonly moduleUniverse: string
+  readonly documentPaths: readonly string[]
+  readonly areaPaths: readonly string[]
+  readonly symbols: ReadonlyMap<string, readonly string[]>
+}): string =>
+  sha256NormalizedV1({
+    moduleUniverse: input.moduleUniverse,
+    documents: [...input.documentPaths].sort(),
+    areas: [...input.areaPaths].sort(),
+    symbols: [...input.symbols.entries()].map(([name, owners]) => [name, [...owners].sort()]).sort(([a], [b]) => String(a).localeCompare(String(b))),
+  })
+
+/**
+ * Index a previous snapshot for reuse, and recompute the fingerprints it was built under.
+ *
+ * The fingerprints are derived rather than stored: everything they cover is in the snapshot
+ * already, and a stored fingerprint is one more thing that can be stale or forged.
+ */
+export const indexPriorSnapshot = (previous: PreviousSnapshot, compilerOptions: unknown): PriorSnapshot => {
+  const outgoing = new Map<string, KnowledgeRelation[]>()
+  for (const relation of previous.relations) {
+    const list = outgoing.get(relation.from)
+    if (list) list.push(relation)
+    else outgoing.set(relation.from, [relation])
+  }
+
+  const collect = (kind: string, prefixes: readonly string[]): Map<string, PriorFile> => {
+    const paths = new Map<string, KnowledgeEntity>()
+    for (const entity of previous.entities) {
+      if (entity.kind !== kind || !entity.path) continue
+      if (hashOf(entity)) paths.set(entity.path, entity)
+    }
+
+    /*
+     * Per-file coverage, matched back to its file.
+     *
+     * The scope is `<topic>:<path>` or `<topic>:<path>:<detail>`, and a detail can itself contain
+     * a colon, so the path is recovered by trimming from the right until a file is recognised
+     * rather than by splitting on the first one.
+     */
+    const coverage = new Map<string, Coverage[]>()
+    for (const entry of previous.coverage) {
+      const prefix = prefixes.find((candidate) => entry.scope.startsWith(candidate))
+      if (!prefix) continue
+      let remainder = entry.scope.slice(prefix.length)
+      while (remainder && !paths.has(remainder)) {
+        const cut = remainder.lastIndexOf(':')
+        remainder = cut < 0 ? '' : remainder.slice(0, cut)
+      }
+      if (!remainder) continue
+      const list = coverage.get(remainder)
+      if (list) list.push(entry)
+      else coverage.set(remainder, [entry])
+    }
+
+    const result = new Map<string, PriorFile>()
+    for (const [path, entity] of paths) {
+      result.set(path, {
+        entity,
+        contentHash: hashOf(entity) as string,
+        outgoing: outgoing.get(entity.id) ?? [],
+        coverage: coverage.get(path) ?? [],
+      })
+    }
+    return result
+  }
+
+  const modules = collect('module', MODULE_COVERAGE_PREFIXES)
+  const documents = collect('document', DOCUMENT_COVERAGE_PREFIXES)
+  const packages = previous.entities
+    .filter((entity) => entity.kind === 'package')
+    .map((entity) => ({ id: entity.id, path: entity.path ?? '.', ...(entity.name ? { name: entity.name } : {}) }))
+
+  const symbols = new Map<string, readonly string[]>()
+  const declaring = new Map<string, string[]>()
+  const forwarding = new Map<string, string[]>()
+  for (const [, file] of modules) {
+    const declared = new Set(declaredExportsOf(file.entity))
+    for (const name of exportsOf(file.entity)) {
+      if (name === '*' || name === 'default') continue
+      const target = declared.has(name) ? declaring : forwarding
+      const list = target.get(name)
+      if (list) list.push(file.entity.id)
+      else target.set(name, [file.entity.id])
+    }
+  }
+  for (const [name, owners] of declaring) symbols.set(name, owners)
+  for (const [name, owners] of forwarding) if (!symbols.has(name)) symbols.set(name, owners)
+
+  const moduleUniverse = moduleUniverseFingerprint({
+    modulePaths: [...modules.keys()],
+    packages,
+    compilerOptions,
+  })
+
+  return {
+    modules,
+    documents,
+    moduleUniverse,
+    resolution: resolutionFingerprint({
+      moduleUniverse,
+      documentPaths: [...documents.keys()],
+      areaPaths: previous.entities.filter((entity) => entity.kind === 'area').map((entity) => entity.path ?? ''),
+      symbols,
+    }),
+    entities: new Map(previous.entities.map((entity) => [entity.id, entity])),
+  }
+}
+
+export type ReuseLedger = {
+  /** Entities taken from the previous snapshot instead of recomputed. */
+  reusedEntities: number
+  /** Files whose syntax tree or Markdown tree had to be built. */
+  parsedFiles: string[]
+  /** Files whose parse was skipped entirely. */
+  skippedFiles: string[]
+  /** Why relation reuse was refused, when it was. */
+  invalidated: string[]
+}
+
+export const emptyLedger = (): ReuseLedger => ({ reusedEntities: 0, parsedFiles: [], skippedFiles: [], invalidated: [] })
+
+/** How many file paths a coverage reason lists before it stops being readable. */
+const LISTED_PATHS = 8
+
+/**
+ * The reuse, as coverage.
+ *
+ * A run that is ten times faster than the last one has to be able to say why, or nobody can tell
+ * a working cache from a broken scan.
+ */
+export const reuseCoverage = (ledger: ReuseLedger): Coverage => {
+  const total = ledger.skippedFiles.length + ledger.parsedFiles.length
+  if (!ledger.skippedFiles.length && !ledger.invalidated.length) {
+    return {
+      analyzer: 'repository',
+      scope: 'reused-entities',
+      status: 'not-applicable',
+      reason: `No previous snapshot was reused; parsed ${total} file(s).`,
+    }
+  }
+  const listed = [...ledger.parsedFiles].sort().slice(0, LISTED_PATHS)
+  const remainder = ledger.parsedFiles.length - listed.length
+  return {
+    analyzer: 'repository',
+    scope: 'reused-entities',
+    status: ledger.invalidated.length ? 'partial' : 'complete',
+    reason: [
+      `Reused ${ledger.reusedEntities} entit${ledger.reusedEntities === 1 ? 'y' : 'ies'} and skipped ${ledger.skippedFiles.length} of ${total} parse(s).`,
+      ledger.parsedFiles.length
+        ? `Re-parsed: ${listed.join(', ')}${remainder > 0 ? ` and ${remainder} more` : ''}.`
+        : 'Nothing needed re-parsing.',
+      ...ledger.invalidated.map((reason) => `Reuse refused: ${reason}.`),
+    ].join(' '),
+  }
+}
+
+/**
+ * Replay a reused entity's outgoing relations against the entity set that exists now.
+ *
+ * A relation whose internal target is gone is dropped rather than carried: the file it pointed at
+ * was renamed or deleted, and a graph that keeps the edge is lying about the repository. An
+ * external endpoint is re-added instead, because an external entity only exists in the snapshot
+ * because something referenced it, and the thing that referenced it is exactly what was reused.
+ */
+export const replayableRelations = (
+  outgoing: readonly KnowledgeRelation[],
+  existing: (id: string) => boolean,
+): {
+  readonly relations: readonly KnowledgeRelation[]
+  readonly missingEndpoints: readonly string[]
+  readonly dropped: readonly KnowledgeRelation[]
+} => {
+  const relations: KnowledgeRelation[] = []
+  const missingEndpoints: string[] = []
+  const dropped: KnowledgeRelation[] = []
+  for (const relation of outgoing) {
+    if (existing(relation.to)) {
+      relations.push(relation)
+      continue
+    }
+    if (relation.to.startsWith('external:') || relation.to.startsWith('unresolved:')) {
+      missingEndpoints.push(relation.to)
+      relations.push(relation)
+      continue
+    }
+    dropped.push(relation)
+  }
+  return { relations, missingEndpoints, dropped }
+}