@agentskit/doc-bridge 1.7.44 → 1.9.0

package/src/enrich/context-pack.ts

@@ -0,0 +1,272 @@
+import { readFileSync } from 'node:fs'
+import { join, resolve } from 'node:path'
+
+import type { DocBridgeConfigV1 } from '../config/schema.js'
+import { sha256NormalizedV1 } from '../index-builder/content-hash.js'
+import { redactSecrets, redactValue } from '../safety/repository.js'
+import type { DiscoverySnapshotV1, Evidence, KnowledgeDiagnostic, KnowledgeEntity, ReconciliationReportV1 } from '../schemas/knowledge.js'
+import { entityContentHash } from './validate.js'
+
+/**
+ * Context packs: what an agent receives instead of the snapshot.
+ *
+ * `ak-docs suggest` sent the whole redacted snapshot — 740 KB on this repository — in one call,
+ * for every question. A pack is one entity, its depth-one neighbours, the open diagnostics that
+ * touch it and a bounded excerpt of its own file, built in a fixed order and truncated in a fixed
+ * order under a byte budget. Cost becomes proportional to what changed, because the pack hash
+ * covers exactly the content hashes the pack is built from, and a pack whose hash has not moved
+ * is a pack the cache already answered.
+ */
+
+export const CONTEXT_PACK_VERSION = 1 as const
+export const DEFAULT_PACK_BYTES = 64 * 1024
+export const MAX_PACK_NEIGHBOURS = 32
+const MAX_PACK_DIAGNOSTICS = 16
+const MAX_EXCERPT_BYTES = 12 * 1024
+const MAX_MESSAGE = 512
+const MAX_METADATA_STRING = 512
+
+export type EnrichmentTask = 'curate' | 'review' | 'adjudicate'
+
+export type PackNeighbour = {
+  readonly id: string
+  readonly kind: string
+  readonly name: string
+  readonly path?: string
+  readonly contentHash: string
+  readonly relation: string
+  readonly direction: 'out' | 'in'
+}
+
+export type PackDiagnostic = Pick<KnowledgeDiagnostic, 'id' | 'code' | 'status' | 'severity'> & { readonly message: string }
+
+export type PackEvidence = {
+  readonly path: string
+  readonly contentHash: string
+  /** Redacted, bounded, possibly truncated — `truncated` says so. */
+  readonly excerpt: string
+  readonly truncated: boolean
+}
+
+export type ContextPack = {
+  readonly type: 'context-pack'
+  readonly schemaVersion: typeof CONTEXT_PACK_VERSION
+  /** Over the target's and every neighbour's content hash: the pack's identity for the cache. */
+  readonly packHash: string
+  readonly baseSnapshotHash: string
+  readonly areaId: string
+  readonly target: {
+    readonly id: string
+    readonly kind: string
+    readonly name: string
+    readonly path?: string
+    readonly contentHash: string
+    readonly aliases: readonly string[]
+    /** The entity's own evidence items: what a proposal about it may cite, verbatim. */
+    readonly evidence: readonly Pick<Evidence, 'source' | 'path' | 'lineStart' | 'lineEnd'>[]
+    readonly metadata: Readonly<Record<string, unknown>>
+  }
+  readonly neighbours: readonly PackNeighbour[]
+  readonly diagnostics: readonly PackDiagnostic[]
+  readonly evidence: readonly PackEvidence[]
+  /**
+   * `bytes` is the serialised size measured with this field at its widest (`maxBytes`), so the
+   * value written is never smaller than the pack it describes and never exceeds the budget.
+   */
+  readonly budget: { readonly maxBytes: number; readonly bytes: number; readonly dropped: readonly string[] }
+}
+
+export type BuildContextPacksOptions = {
+  readonly snapshot: Pick<DiscoverySnapshotV1, 'contentHash' | 'entities' | 'relations'>
+  readonly report?: Pick<ReconciliationReportV1, 'diagnostics'>
+  readonly config?: DocBridgeConfigV1
+  /** Which entity kinds to build packs for. Defaults to documents. */
+  readonly kinds?: readonly string[]
+  /** Only these entity ids. Unset means every entity of the selected kinds. */
+  readonly targets?: ReadonlySet<string>
+  /** File contents by repository-relative path. Defaults to reading under `root`. */
+  readonly readFile?: (path: string) => string | undefined
+  readonly root?: string
+}
+
+export const packByteBudget = (config: DocBridgeConfigV1 | undefined): number => config?.intelligence?.registry?.maxPackBytes ?? DEFAULT_PACK_BYTES
+
+const bytes = (value: unknown): number => Buffer.byteLength(JSON.stringify(value), 'utf8')
+
+const boundedMetadata = (metadata: Record<string, unknown> | undefined): Record<string, unknown> => {
+  const out: Record<string, unknown> = {}
+  for (const key of Object.keys(metadata ?? {}).sort()) {
+    const value = metadata?.[key]
+    if (typeof value === 'string') out[key] = redactSecrets(value).slice(0, MAX_METADATA_STRING)
+    else if (typeof value === 'number' || typeof value === 'boolean') out[key] = value
+    else if (Array.isArray(value)) out[key] = redactValue(value.slice(0, 64))
+    else if (value && typeof value === 'object') out[key] = redactValue(value)
+  }
+  return out
+}
+
+const defaultReader = (root: string | undefined) => (path: string): string | undefined => {
+  if (!root) return undefined
+  try {
+    return readFileSync(join(resolve(root), path), 'utf8')
+  } catch {
+    return undefined
+  }
+}
+
+/** The area a path belongs to: the most specific area entity whose path prefixes it. */
+const areaFor = (path: string | undefined, areas: readonly KnowledgeEntity[]): string => {
+  if (!path) return 'root'
+  let best: KnowledgeEntity | undefined
+  for (const area of areas) {
+    const areaPath = area.path?.replace(/\/$/, '')
+    if (!areaPath) continue
+    if (path === areaPath || path.startsWith(`${areaPath}/`)) {
+      if (!best || areaPath.length > (best.path?.length ?? 0)) best = area
+    }
+  }
+  return best?.id ?? 'root'
+}
+
+/**
+ * Fit a pack under its budget by dropping in a declared order: excerpt bytes first (halved
+ * until it fits, then dropped), then diagnostics from the end, then neighbours from the end.
+ * The target itself is never dropped — a pack with no target is not a pack.
+ *
+ * This mirrors `compileBudget` from `@agentskit/core` with a byte counter and the
+ * `drop-oldest` strategy over sections ordered least-important-first; a test cross-checks the
+ * two so the mirror cannot drift, and the mirror is what runs, because a pack must be the same
+ * pack whether or not an optional peer is installed.
+ */
+export const fitContextPack = (pack: ContextPack, maxBytes: number): ContextPack => {
+  let current: ContextPack = { ...pack, budget: { maxBytes, bytes: maxBytes, dropped: [] } }
+  const dropped: string[] = []
+  const measure = (): number => bytes({ ...current, budget: { maxBytes, bytes: maxBytes, dropped } })
+  let size = measure()
+  while (size > maxBytes && current.evidence.some((item) => item.excerpt.length > 0)) {
+    current = {
+      ...current,
+      evidence: current.evidence.map((item) => {
+        if (!item.excerpt.length) return item
+        const next = item.excerpt.length > 256 ? item.excerpt.slice(0, Math.floor(item.excerpt.length / 2)) : ''
+        return { ...item, excerpt: next, truncated: true }
+      }),
+    }
+    if (!dropped.includes('evidence.excerpt')) dropped.push('evidence.excerpt')
+    size = measure()
+  }
+  while (size > maxBytes && current.diagnostics.length) {
+    current = { ...current, diagnostics: current.diagnostics.slice(0, -1) }
+    if (!dropped.includes('diagnostics')) dropped.push('diagnostics')
+    size = measure()
+  }
+  while (size > maxBytes && current.neighbours.length) {
+    current = { ...current, neighbours: current.neighbours.slice(0, -1) }
+    if (!dropped.includes('neighbours')) dropped.push('neighbours')
+    size = measure()
+  }
+  return { ...current, budget: { maxBytes, bytes: measure(), dropped } }
+}
+
+/** The pack hash: the target and its neighbours by content hash, nothing else. */
+export const contextPackHash = (target: { readonly id: string; readonly contentHash: string }, neighbours: readonly Pick<PackNeighbour, 'id' | 'contentHash'>[]): string =>
+  sha256NormalizedV1({
+    version: CONTEXT_PACK_VERSION,
+    target: { id: target.id, contentHash: target.contentHash },
+    neighbours: [...neighbours].map((item) => ({ id: item.id, contentHash: item.contentHash })).sort((left, right) => left.id.localeCompare(right.id)),
+  })
+
+/**
+ * Build one pack per target entity, in id order.
+ *
+ * Neighbours are the other ends of every relation touching the target, sorted by kind then id
+ * and capped; diagnostics are the open ones naming the target or citing its file; the excerpt is
+ * the target's own file, read only if its bytes still hash to what the snapshot recorded.
+ */
+export const buildContextPacks = (options: BuildContextPacksOptions): ContextPack[] => {
+  const { snapshot } = options
+  const kinds = new Set(options.kinds ?? ['document'])
+  const readFile = options.readFile ?? defaultReader(options.root)
+  const maxBytes = packByteBudget(options.config)
+  const entities = new Map(snapshot.entities.map((entity) => [entity.id, entity]))
+  const areas = snapshot.entities.filter((entity) => entity.kind === 'area')
+  const touching = new Map<string, { readonly other: string; readonly relation: string; readonly direction: 'out' | 'in' }[]>()
+  const push = (id: string, item: { other: string; relation: string; direction: 'out' | 'in' }): void => {
+    const list = touching.get(id)
+    if (list) list.push(item)
+    else touching.set(id, [item])
+  }
+  for (const relation of snapshot.relations) {
+    push(relation.from, { other: relation.to, relation: relation.kind, direction: 'out' })
+    push(relation.to, { other: relation.from, relation: relation.kind, direction: 'in' })
+  }
+  const open = (options.report?.diagnostics ?? []).filter((diagnostic) => diagnostic.status !== 'confirmed')
+
+  const packs: ContextPack[] = []
+  for (const entity of [...snapshot.entities].sort((left, right) => left.id.localeCompare(right.id))) {
+    if (!kinds.has(entity.kind)) continue
+    if (options.targets && !options.targets.has(entity.id)) continue
+    const contentHash = entityContentHash(entity)
+    const neighbours: PackNeighbour[] = (touching.get(entity.id) ?? [])
+      .flatMap((item) => {
+        const other = entities.get(item.other)
+        return other
+          ? [{ id: other.id, kind: other.kind, name: other.name, ...(other.path ? { path: other.path } : {}), contentHash: entityContentHash(other), relation: item.relation, direction: item.direction }]
+          : []
+      })
+      .sort((left, right) => left.kind.localeCompare(right.kind) || left.id.localeCompare(right.id) || left.relation.localeCompare(right.relation))
+      .filter((item, index, all) => index === 0 || item.id !== all[index - 1]?.id || item.relation !== all[index - 1]?.relation)
+      .slice(0, MAX_PACK_NEIGHBOURS)
+    const diagnostics: PackDiagnostic[] = open
+      .filter((diagnostic) => diagnostic.entityIds?.includes(entity.id) || (entity.path !== undefined && diagnostic.evidence.some((item) => item.path === entity.path)))
+      .sort((left, right) => left.id.localeCompare(right.id))
+      .slice(0, MAX_PACK_DIAGNOSTICS)
+      .map((diagnostic) => ({ id: diagnostic.id, code: diagnostic.code, status: diagnostic.status, severity: diagnostic.severity, message: redactSecrets(diagnostic.message).slice(0, MAX_MESSAGE) }))
+    const evidence: PackEvidence[] = []
+    if (entity.path && entity.evidence[0]?.contentHash) {
+      const raw = readFile(entity.path)
+      // A file that no longer hashes to the entity is not the entity's file: the pack describes the snapshot.
+      if (raw !== undefined && sha256NormalizedV1(raw.replace(/^/, '')) === entity.evidence[0].contentHash) {
+        const redacted = redactSecrets(raw)
+        const truncated = Buffer.byteLength(redacted, 'utf8') > MAX_EXCERPT_BYTES
+        evidence.push({ path: entity.path, contentHash: entity.evidence[0].contentHash, excerpt: truncated ? redacted.slice(0, MAX_EXCERPT_BYTES) : redacted, truncated })
+      }
+    }
+    const draft: ContextPack = {
+      type: 'context-pack',
+      schemaVersion: CONTEXT_PACK_VERSION,
+      packHash: contextPackHash({ id: entity.id, contentHash }, neighbours),
+      baseSnapshotHash: snapshot.contentHash,
+      areaId: entity.kind === 'area' ? entity.id : areaFor(entity.path, areas),
+      target: {
+        id: entity.id,
+        kind: entity.kind,
+        name: redactSecrets(entity.name),
+        ...(entity.path ? { path: entity.path } : {}),
+        contentHash,
+        aliases: [...(entity.aliases ?? [])].map(redactSecrets).sort(),
+        evidence: entity.evidence.slice(0, 8).map((item) => ({ source: item.source, path: item.path, ...(item.lineStart !== undefined ? { lineStart: item.lineStart } : {}), ...(item.lineEnd !== undefined ? { lineEnd: item.lineEnd } : {}) })),
+        metadata: boundedMetadata(entity.metadata),
+      },
+      neighbours,
+      diagnostics,
+      evidence,
+      budget: { maxBytes, bytes: 0, dropped: [] },
+    }
+    packs.push(fitContextPack(draft, maxBytes))
+  }
+  return packs
+}
+
+/** Packs grouped by area, areas in id order, packs in id order within each: one batch per call. */
+export const batchContextPacks = (packs: readonly ContextPack[]): readonly { readonly areaId: string; readonly packs: readonly ContextPack[] }[] => {
+  const groups = new Map<string, ContextPack[]>()
+  for (const pack of packs) {
+    const list = groups.get(pack.areaId)
+    if (list) list.push(pack)
+    else groups.set(pack.areaId, [pack])
+  }
+  return [...groups.entries()]
+    .sort(([left], [right]) => left.localeCompare(right))
+    .map(([areaId, list]) => ({ areaId, packs: [...list].sort((left, right) => left.target.id.localeCompare(right.target.id)) }))
+}

package/src/enrich/overlay.ts

@@ -0,0 +1,255 @@
+import { existsSync, mkdirSync, readFileSync, renameSync, writeFileSync } from 'node:fs'
+import { join, resolve } from 'node:path'
+
+import { sha256NormalizedV1 } from '../index-builder/content-hash.js'
+import type { RetrievalOverlayInput } from '../retrieval/project.js'
+import {
+  ENRICHMENT_POLICY,
+  EnrichmentOverlayV1Schema,
+  enrichmentOverlayContentHash,
+  type AcceptedEnrichment,
+  type EnrichmentOverlayV1,
+  type EnrichmentProposalOf,
+} from '../schemas/enrichment.js'
+import type { DiscoverySnapshotV1, KnowledgeEntity, KnowledgeRelation } from '../schemas/knowledge.js'
+import { entityContentHash } from './validate.js'
+
+/**
+ * The overlay on disk, and what the deterministic layer reads from it.
+ *
+ * The file is written by the enrich stage and by an approval; it is never written by a read.
+ * `index`, `search`, `query` and MCP consult it through `projectEnrichmentOverlay`, which is a
+ * pure function of the overlay and the snapshot: an accepted entry whose target hash no longer
+ * matches its entity is expired *in the result*, not in the file, so a stale entry costs nothing
+ * and a read leaves no trace.
+ */
+
+export const ENRICHMENT_DIR = '.doc-bridge/enrich'
+export const ENRICHMENT_OVERLAY_FILE = 'overlay.json'
+
+export const enrichmentDir = (root: string): string => join(resolve(root), ENRICHMENT_DIR)
+export const enrichmentOverlayPath = (root: string): string => join(enrichmentDir(root), ENRICHMENT_OVERLAY_FILE)
+export const enrichmentCacheDir = (root: string): string => join(enrichmentDir(root), 'cache')
+
+/**
+ * Read the overlay, or nothing.
+ *
+ * Missing, unreadable, malformed or failing its own hash all mean the same thing to a reader:
+ * there is no overlay. Failing closed here is what keeps a corrupt file from changing a `check`
+ * result — a reader that threw would make the deterministic layer depend on the enrichment one.
+ */
+export const readEnrichmentOverlay = (root: string): EnrichmentOverlayV1 | undefined => {
+  const path = enrichmentOverlayPath(root)
+  if (!existsSync(path)) return undefined
+  try {
+    const parsed = EnrichmentOverlayV1Schema.parse(JSON.parse(readFileSync(path, 'utf8')) as unknown)
+    return parsed.contentHash === enrichmentOverlayContentHash(parsed) ? parsed : undefined
+  } catch {
+    return undefined
+  }
+}
+
+/** Parse an overlay from memory with the same rules as a read: schema and hash, or nothing. */
+export const parseEnrichmentOverlay = (value: unknown): EnrichmentOverlayV1 | undefined => {
+  const parsed = EnrichmentOverlayV1Schema.safeParse(value)
+  return parsed.success && parsed.data.contentHash === enrichmentOverlayContentHash(parsed.data) ? parsed.data : undefined
+}
+
+export const writeEnrichmentOverlay = (root: string, overlay: EnrichmentOverlayV1): string => {
+  const path = enrichmentOverlayPath(root)
+  mkdirSync(enrichmentDir(root), { recursive: true })
+  const sealed = EnrichmentOverlayV1Schema.parse({ ...overlay, contentHash: enrichmentOverlayContentHash(overlay) })
+  const temporary = `${path}.tmp-${process.pid}`
+  writeFileSync(temporary, `${JSON.stringify(sealed, null, 2)}\n`, 'utf8')
+  renameSync(temporary, path)
+  return path
+}
+
+/** Seal an overlay: every list sorted, the hash recomputed. The shape every writer goes through. */
+export const sealEnrichmentOverlay = (overlay: Omit<EnrichmentOverlayV1, 'contentHash'>): EnrichmentOverlayV1 => {
+  const sorted = {
+    ...overlay,
+    accepted: [...overlay.accepted].sort((left, right) => left.proposal.proposalId.localeCompare(right.proposal.proposalId)),
+    pending: [...overlay.pending].sort((left, right) => left.proposal.proposalId.localeCompare(right.proposal.proposalId)),
+    rejected: [...overlay.rejected].sort((left, right) => left.proposalId.localeCompare(right.proposalId) || left.reason.localeCompare(right.reason)),
+  }
+  return EnrichmentOverlayV1Schema.parse({ ...sorted, contentHash: enrichmentOverlayContentHash(sorted) })
+}
+
+export type EffectiveOverlay = {
+  /** Accepted entries whose target still has the hash they were made against. */
+  readonly live: readonly AcceptedEnrichment[]
+  /** Accepted entries whose target moved: excluded from every projection, left in the file. */
+  readonly expired: readonly AcceptedEnrichment[]
+}
+
+/**
+ * Per-entry staleness.
+ *
+ * An entry binds to the content hash of the entity it describes, not to the snapshot hash, so one
+ * changed file expires one entry and its siblings survive. An entity that no longer exists expires
+ * its entries too: there is nothing left to describe.
+ */
+export const effectiveEnrichment = (overlay: Pick<EnrichmentOverlayV1, 'accepted'>, snapshot: Pick<DiscoverySnapshotV1, 'entities'>): EffectiveOverlay => {
+  const hashes = new Map(snapshot.entities.map((entity) => [entity.id, entityContentHash(entity)]))
+  const live: AcceptedEnrichment[] = []
+  const expired: AcceptedEnrichment[] = []
+  for (const entry of overlay.accepted) {
+    const current = hashes.get(entry.proposal.entity)
+    const still = current !== undefined && current === entry.proposal.targetContentHash && endpointsPresent(entry, hashes)
+    ;(still ? live : expired).push(entry)
+  }
+  return { live, expired }
+}
+
+/** A relation or a flag names a second entity; if that one is gone, the entry has nothing to point at. */
+const endpointsPresent = (entry: AcceptedEnrichment, hashes: ReadonlyMap<string, string>): boolean => {
+  const { proposal } = entry
+  switch (proposal.kind) {
+    case 'propose-relation':
+      return hashes.has(proposal.payload.from) && hashes.has(proposal.payload.to)
+    case 'mark-canonical':
+      return hashes.has(proposal.payload.scope)
+    case 'flag-contradiction':
+      return hashes.has(proposal.payload.against)
+    case 'flag-redundancy':
+      return hashes.has(proposal.payload.with)
+    case 'flag-gap':
+      return hashes.has(proposal.payload.area)
+    default:
+      return true
+  }
+}
+
+/** The hash of what an overlay contributes: the live accepted set. Empty when nothing is live. */
+export const enrichmentOverlayHash = (live: readonly AcceptedEnrichment[]): string =>
+  sha256NormalizedV1({
+    accepted: [...live]
+      .map((entry) => ({ proposalId: entry.proposal.proposalId, targetContentHash: entry.proposal.targetContentHash }))
+      .sort((left, right) => left.proposalId.localeCompare(right.proposalId)),
+  })
+
+/** Signals are shares of the bounded weight: a strong hint is the full share, a canonical marker most of it, a weak hint half. */
+const SIGNAL_STRONG = 1
+const SIGNAL_CANONICAL = 0.8
+const SIGNAL_WEAK = 0.5
+
+const relationOf = (proposal: EnrichmentProposalOf<'propose-relation'>): KnowledgeRelation => ({
+  id: `relation:${proposal.payload.from}|${proposal.payload.kind}|${proposal.payload.to}|proposed:${proposal.proposalId.slice(0, 12)}`,
+  kind: proposal.payload.kind,
+  from: proposal.payload.from,
+  to: proposal.payload.to,
+  provenance: 'proposed',
+  evidence: proposal.evidence,
+  metadata: { proposalId: proposal.proposalId, detection: proposal.payload.detection, confidence: 'proposed', agentId: proposal.origin.agentId },
+})
+
+/**
+ * What the projection reads from an overlay: aliases, summaries, intents, canonical markers,
+ * rank hints and relations, each already expired against the snapshot.
+ *
+ * Findings (`flag-*`) and area suggestions contribute nothing here on purpose. A gap is a thing to
+ * review, not a fact to rank on; an area suggestion becomes configuration or nothing.
+ */
+export const projectEnrichmentOverlay = (
+  overlay: EnrichmentOverlayV1 | undefined,
+  snapshot: Pick<DiscoverySnapshotV1, 'entities'>,
+): RetrievalOverlayInput | undefined => {
+  if (!overlay) return undefined
+  const { live } = effectiveEnrichment(overlay, snapshot)
+  const signals = new Map<string, number>()
+  const aliases = new Map<string, string[]>()
+  const summaries = new Map<string, string>()
+  const canonical = new Map<string, string>()
+  const intents: { id: string; title: string; paths: string[]; language: string }[] = []
+  const relations: KnowledgeRelation[] = []
+  const paths = new Map(snapshot.entities.map((entity) => [entity.id, entity.path]))
+  const bump = (id: string, share: number): void => {
+    signals.set(id, Math.min(1, (signals.get(id) ?? 0) + share))
+  }
+
+  for (const entry of live) {
+    const { proposal } = entry
+    switch (proposal.kind) {
+      case 'add-alias':
+        aliases.set(proposal.entity, [...(aliases.get(proposal.entity) ?? []), proposal.payload.alias])
+        break
+      case 'summarize':
+        if (!summaries.has(proposal.entity)) summaries.set(proposal.entity, proposal.payload.summary)
+        break
+      case 'add-intent':
+        intents.push({
+          id: `intent:proposed:${proposal.proposalId.slice(0, 16)}`,
+          title: proposal.payload.phrase,
+          paths: [paths.get(proposal.entity) ?? proposal.entity],
+          language: proposal.payload.language,
+        })
+        break
+      case 'mark-canonical':
+        canonical.set(proposal.entity, proposal.payload.scope)
+        bump(proposal.entity, SIGNAL_CANONICAL)
+        break
+      case 'rank-hint':
+        bump(proposal.entity, proposal.payload.relevance === 'strong' ? SIGNAL_STRONG : SIGNAL_WEAK)
+        break
+      case 'propose-relation':
+        relations.push(relationOf(proposal))
+        break
+      default:
+        break
+    }
+  }
+  for (const list of aliases.values()) list.sort()
+  intents.sort((left, right) => left.id.localeCompare(right.id))
+  relations.sort((left, right) => left.id.localeCompare(right.id))
+  return {
+    hash: enrichmentOverlayHash(live),
+    ...(signals.size ? { signals } : {}),
+    ...(aliases.size ? { aliases } : {}),
+    ...(summaries.size ? { summaries } : {}),
+    ...(canonical.size ? { canonical } : {}),
+    ...(intents.length ? { intents } : {}),
+    ...(relations.length ? { relations } : {}),
+  }
+}
+
+/**
+ * The snapshot plus the live accepted relations, for the graph, the report and the memory view.
+ *
+ * Additive only: every observed entity and relation is carried unchanged, and a proposed relation
+ * whose id collides with an observed one is dropped rather than allowed to shadow it. The
+ * assertion below is what the projection tests run; it is here so any consumer can run it.
+ */
+export const withAcceptedRelations = <T extends Pick<DiscoverySnapshotV1, 'entities' | 'relations'>>(
+  snapshot: T,
+  overlay: EnrichmentOverlayV1 | undefined,
+): T => {
+  if (!overlay) return snapshot
+  const { live } = effectiveEnrichment(overlay, snapshot)
+  const observedIds = new Set(snapshot.relations.map((relation) => relation.id))
+  const proposed = live
+    .flatMap((entry) => (entry.proposal.kind === 'propose-relation' ? [relationOf(entry.proposal as EnrichmentProposalOf<'propose-relation'>)] : []))
+    .filter((relation) => !observedIds.has(relation.id))
+    .sort((left, right) => left.id.localeCompare(right.id))
+  if (!proposed.length) return snapshot
+  const merged = { ...snapshot, relations: [...snapshot.relations, ...proposed] }
+  assertObservedSurvive(snapshot, merged)
+  return merged
+}
+
+/** Every observed entity and relation must be present, unchanged, after enrichment. */
+export const assertObservedSurvive = (
+  observed: Pick<DiscoverySnapshotV1, 'entities' | 'relations'>,
+  enriched: Pick<DiscoverySnapshotV1, 'entities' | 'relations'>,
+): void => {
+  const entities = new Map(enriched.entities.map((entity) => [entity.id, entity]))
+  const relations = new Map(enriched.relations.map((relation) => [relation.id, relation]))
+  const same = (left: KnowledgeEntity | KnowledgeRelation, right: KnowledgeEntity | KnowledgeRelation | undefined): boolean =>
+    right !== undefined && sha256NormalizedV1(left) === sha256NormalizedV1(right)
+  for (const entity of observed.entities) if (!same(entity, entities.get(entity.id))) throw new Error(`Enrichment removed or altered observed entity ${entity.id}.`)
+  for (const relation of observed.relations) if (!same(relation, relations.get(relation.id))) throw new Error(`Enrichment removed or altered observed relation ${relation.id}.`)
+}
+
+/** Accepted entries that are findings rather than facts, for a reviewer or a renderer. */
+export const enrichmentFindings = (overlay: EnrichmentOverlayV1): readonly AcceptedEnrichment[] =>
+  overlay.accepted.filter((entry) => ENRICHMENT_POLICY[entry.proposal.kind] === 'finding')

package/src/enrich/review.ts

@@ -0,0 +1,106 @@
+import { ENRICHMENT_POLICY, type AcceptedEnrichment, type EnrichmentOverlayV1, type PendingEnrichment, type RejectedEnrichment } from '../schemas/enrichment.js'
+import type { DiscoverySnapshotV1 } from '../schemas/knowledge.js'
+import { approvalsDir, createFileApprovalStore, enrichmentApprovalId, loadApprovalGate, ENRICHMENT_APPROVAL_GATE, type ApprovalGate } from './approvals.js'
+import { effectiveEnrichment, readEnrichmentOverlay, sealEnrichmentOverlay, writeEnrichmentOverlay } from './overlay.js'
+import { entityContentHash } from './validate.js'
+
+/**
+ * Reviewing the overlay: what a person does with it.
+ *
+ * Shared by `ak-docs enrich list|approve|reject`, the MCP `docbridge.proposals` tool and a
+ * rendered review page, so there is one way to decide and one record of the decision. A
+ * decision goes through the approval gate first and the overlay second: if the gate refuses —
+ * already decided, unknown — the overlay is untouched.
+ */
+
+export type EnrichmentReview = {
+  readonly overlayHash: string
+  readonly baseSnapshotHash: string
+  readonly accepted: readonly AcceptedEnrichment[]
+  readonly pending: readonly PendingEnrichment[]
+  readonly rejected: readonly RejectedEnrichment[]
+  readonly stats: EnrichmentOverlayV1['stats']
+}
+
+export const listEnrichment = (root: string): EnrichmentReview | undefined => {
+  const overlay = readEnrichmentOverlay(root)
+  if (!overlay) return undefined
+  return { overlayHash: overlay.contentHash, baseSnapshotHash: overlay.baseSnapshotHash, accepted: overlay.accepted, pending: overlay.pending, rejected: overlay.rejected, stats: overlay.stats }
+}
+
+export type DecideEnrichmentOptions = {
+  readonly root: string
+  readonly proposalId: string
+  readonly decision: 'approved' | 'rejected'
+  /** Who decided. Must not be the proposal's author, and must not be `policy`. */
+  readonly by: string
+  readonly reason?: string
+  /** When given, the proposal must still describe the entity as it is now. */
+  readonly snapshot?: Pick<DiscoverySnapshotV1, 'entities'>
+  readonly gate?: ApprovalGate
+  readonly now?: () => string
+}
+
+export type DecideEnrichmentResult = {
+  readonly overlay: EnrichmentOverlayV1
+  readonly approvalId: string
+  readonly entry: AcceptedEnrichment | RejectedEnrichment
+  readonly gateSource: 'ecosystem' | 'mirror' | 'supplied'
+}
+
+/**
+ * Approve or reject one pending proposal.
+ *
+ * Binding is to both the proposal id and the target content hash: the approval record's id is
+ * their hash, so an approval given for one version of a document cannot be replayed against the
+ * next one. A person approving their own agent's output is refused by identity, and `policy` is
+ * not a person.
+ */
+export const decideEnrichment = async (options: DecideEnrichmentOptions): Promise<DecideEnrichmentResult> => {
+  const overlay = readEnrichmentOverlay(options.root)
+  if (!overlay) throw new Error('No enrichment overlay to review. Run `ak-docs enrich` first.')
+  const entry = overlay.pending.find((item) => item.proposal.proposalId === options.proposalId || item.proposal.proposalId.startsWith(options.proposalId))
+  if (!entry) throw new Error(`No pending enrichment proposal "${options.proposalId}".`)
+  const { proposal } = entry
+  if (options.by === 'policy') throw new Error(`${proposal.kind} requires a person; "policy" cannot approve it.`)
+  if (options.by === proposal.origin.agentId) throw new Error(`Rejected: "${options.by}" proposed ${proposal.proposalId} and cannot approve its own output.`)
+  if (options.snapshot) {
+    const entity = options.snapshot.entities.find((item) => item.id === proposal.entity)
+    if (!entity || entityContentHash(entity) !== proposal.targetContentHash) throw new Error(`Proposal ${proposal.proposalId} is stale: ${proposal.entity} changed since it was made. Re-run enrichment.`)
+    if (effectiveEnrichment({ accepted: [{ proposal, acceptedAt: '1970-01-01T00:00:00.000Z', acceptedBy: options.by }] }, options.snapshot).live.length !== 1) throw new Error(`Proposal ${proposal.proposalId} names an entity that no longer exists.`)
+  }
+
+  const approvalId = enrichmentApprovalId(proposal.proposalId, proposal.targetContentHash)
+  const loaded = options.gate ? { gate: options.gate, source: 'supplied' as const } : await loadApprovalGate(createFileApprovalStore(approvalsDir(options.root)))
+  const existing = await loaded.gate.request({
+    id: approvalId,
+    name: ENRICHMENT_APPROVAL_GATE,
+    payload: { proposalId: proposal.proposalId, targetContentHash: proposal.targetContentHash, kind: proposal.kind, entity: proposal.entity, policy: ENRICHMENT_POLICY[proposal.kind] },
+  })
+  if (existing.status !== 'pending') throw new Error(`Approval ${approvalId} was already ${existing.status}.`)
+  const approval = await loaded.gate.decide(approvalId, options.decision, { by: options.by, proposalId: proposal.proposalId, targetContentHash: proposal.targetContentHash, ...(options.reason ? { reason: options.reason } : {}) })
+
+  const pending = overlay.pending.filter((item) => item.proposal.proposalId !== proposal.proposalId)
+  const decided: AcceptedEnrichment | RejectedEnrichment =
+    options.decision === 'approved'
+      ? { proposal, acceptedAt: approval.decidedAt ?? (options.now ?? (() => new Date().toISOString()))(), acceptedBy: options.by, approvalId }
+      : { proposalId: proposal.proposalId, kind: proposal.kind, entity: proposal.entity, reason: 'human-rejected', detail: `${options.by}${options.reason ? `: ${options.reason}` : ''}`.slice(0, 1_024), origin: proposal.origin }
+  const stats = { ...overlay.stats, byKind: { ...overlay.stats.byKind }, rejectionReasons: { ...overlay.stats.rejectionReasons } }
+  const counts = { ...(stats.byKind[proposal.kind] ?? { proposed: 0, accepted: 0, pending: 0, rejected: 0 }) }
+  counts.pending = Math.max(0, counts.pending - 1)
+  if (options.decision === 'approved') counts.accepted += 1
+  else {
+    counts.rejected += 1
+    stats.rejectionReasons['human-rejected'] = (stats.rejectionReasons['human-rejected'] ?? 0) + 1
+  }
+  stats.byKind[proposal.kind] = counts
+  const next = sealEnrichmentOverlay({
+    ...overlay,
+    pending,
+    accepted: options.decision === 'approved' ? [...overlay.accepted, decided as AcceptedEnrichment] : overlay.accepted,
+    rejected: options.decision === 'rejected' ? [...overlay.rejected, decided as RejectedEnrichment] : overlay.rejected,
+    stats,
+  })
+  writeEnrichmentOverlay(options.root, next)
+  return { overlay: next, approvalId, entry: decided, gateSource: loaded.source }
+}