@agentskit/doc-bridge 1.7.44 → 1.9.0

package/src/mcp/server.ts

@@ -8,15 +8,20 @@ import { retrieveDocBridgeChunks } from '../retriever/doc-bridge-retriever.js'
 import { runGates } from '../gates/run-gates.js'
 import { ingestMemoryCandidates } from '../memory/ingest.js'
 import { classifyMemoryCandidates, draftMemoryPromotion } from '../memory/pipeline.js'
-import { loadDocBridgeIndex } from '../query/load-index.js'
+import { loadFreshDocBridgeIndex } from '../query/load-index.js'
 import { runQuery } from '../query/query.js'
 import { searchIndex } from '../query/search.js'
+import { findingsFromDiagnostics } from '../findings/report.js'
+import { budgetedHandoff, formatKnowledgeLookupText, formatKnowledgeSearchText, knowledgeLookup, knowledgeSearch, MAX_LOOKUP_DEPTH } from './knowledge.js'
+import type { AgentHandoffV1 } from '../schemas/agent-handoff.js'
+import { RetrievalKindSchema } from '../schemas/retrieval-index.js'
 import type { DocBridgeIndexV1 } from '../schemas/doc-bridge-index.js'
 import { PACKAGE_VERSION } from '../version.js'
 import { loadWorkflowManifest, loadWorkflowStepOutput } from '../workflow/engine.js'
 import { parseDiscoverySnapshot, parseReconciliationReport } from '../validate.js'
 import { applyFixProposal, approveFixProposal, createArtifactNormalizationProposal, createMarkdownLinkFixProposal } from '../fixes/proposals.js'
 import { createRegistryAgentAdapter, loadRegistryAgentRunner, persistRegistryAgentProposal } from '../agents/registry-adapter.js'
+import { decideEnrichment, listEnrichment } from '../enrich/review.js'
 import { sha256NormalizedV1 } from '../index-builder/content-hash.js'
 import { discoverRepository } from '../discovery/repository.js'
 import { FixProposalV1Schema, type DiscoverySnapshotV1, type ReconciliationReportV1, type FixProposalV1 } from '../schemas/knowledge.js'
@@ -43,7 +48,7 @@ export const MCP_TOOLS = [
     annotations: { readOnlyHint: true },
     inputSchema: {
       type: 'object',
-      properties: { id: { type: 'string' }, kind: { type: 'string', enum: ['package', 'ownership'] } },
+      properties: { id: { type: 'string' }, kind: { type: 'string', enum: ['package', 'ownership'] }, budgetTokens: { type: 'number' } },
       required: ['id'],
     },
   },
@@ -54,7 +59,7 @@ export const MCP_TOOLS = [
     annotations: { readOnlyHint: true },
     inputSchema: {
       type: 'object',
-      properties: { term: { type: 'string' }, limit: { type: 'number' } },
+      properties: { term: { type: 'string' }, limit: { type: 'number' }, agent: { type: 'boolean' }, mode: { type: 'string', enum: ['discovery', 'editing', 'debugging', 'documentation'] }, contextBudgetTokens: { type: 'number' } },
       required: ['term'],
     },
   },
@@ -126,7 +131,7 @@ export const MCP_TOOLS = [
     title: 'Read reconciliation diagnostics',
     description: 'Read bounded diagnostics from the latest canonical reconciliation report.',
     annotations: { readOnlyHint: true },
-    inputSchema: { type: 'object', properties: { status: { type: 'string' }, severity: { type: 'string' } } },
+    inputSchema: { type: 'object', properties: { status: { type: 'string' }, severity: { type: 'string' }, format: { type: 'string', enum: ['diagnostic', 'finding'] } } },
   },
   {
     name: 'docbridge.relations',
@@ -146,21 +151,81 @@ export const MCP_TOOLS = [
     name: 'docbridge.proposals',
     title: 'Read or approve proposals',
     description: 'Create, inspect, approve and apply deterministic proposals through the shared human-gated workflow.',
-    inputSchema: { type: 'object', properties: { action: { type: 'string', enum: ['list', 'propose-links', 'propose-normalize', 'suggest', 'approve', 'apply'] }, proposalHash: { type: 'string' }, artifactPath: { type: 'string' }, approvedBy: { type: 'string' }, proposal: { type: 'object' } } },
+    inputSchema: { type: 'object', properties: { action: { type: 'string', enum: ['list', 'propose-links', 'propose-normalize', 'suggest', 'approve', 'apply', 'enrich-list', 'enrich-approve', 'enrich-reject'] }, proposalHash: { type: 'string' }, artifactPath: { type: 'string' }, approvedBy: { type: 'string' }, proposal: { type: 'object' }, proposalId: { type: 'string' }, reason: { type: 'string' } } },
+  },
+  {
+    name: 'knowledge.search',
+    title: 'Search the knowledge graph',
+    description: 'Rank every indexed entity for a query, optionally by kind, with an explanation and within a token budget.',
+    annotations: { readOnlyHint: true },
+    inputSchema: {
+      type: 'object',
+      properties: {
+        query: { type: 'string' },
+        kinds: { type: 'array', items: { type: 'string', enum: ['document', 'module', 'area', 'package', 'intent', 'change'] } },
+        limit: { type: 'number' },
+        explain: { type: 'boolean' },
+        budgetTokens: { type: 'number' },
+        format: { type: 'string', enum: ['json', 'text'] },
+      },
+      required: ['query'],
+    },
+  },
+  {
+    name: 'knowledge.lookup',
+    title: 'Look up one entity',
+    description: 'Return an entity with its neighbours by relation kind, the documents about it, its handoff, its open diagnostics and its evidence, within a token budget.',
+    annotations: { readOnlyHint: true },
+    inputSchema: {
+      type: 'object',
+      properties: {
+        id: { type: 'string' },
+        path: { type: 'string' },
+        depth: { type: 'number' },
+        budgetTokens: { type: 'number' },
+        format: { type: 'string', enum: ['json', 'text'] },
+      },
+    },
   },
 ] as const
 
 const asRecord = (value: unknown): Record<string, unknown> =>
   value && typeof value === 'object' ? (value as Record<string, unknown>) : {}
 
+/** A budget is a positive count of tokens; the upper bound keeps a typo from meaning "unbounded". */
+const BudgetTokensSchema = z.number().int().positive().max(1_000_000)
+
 const HandoffResolveArgsSchema = z.object({
   id: z.string().min(1),
   kind: z.enum(['package', 'ownership']).optional(),
+  budgetTokens: BudgetTokensSchema.optional(),
 })
 
+const KnowledgeSearchArgsSchema = z.object({
+  query: z.string().min(1),
+  kinds: z.array(RetrievalKindSchema).max(6).optional(),
+  limit: z.number().int().positive().max(100).optional(),
+  explain: z.boolean().optional(),
+  budgetTokens: BudgetTokensSchema.optional(),
+  format: z.enum(['json', 'text']).optional(),
+})
+
+const KnowledgeLookupArgsSchema = z
+  .object({
+    id: z.string().min(1).optional(),
+    path: z.string().min(1).optional(),
+    depth: z.number().int().min(1).max(MAX_LOOKUP_DEPTH).optional(),
+    budgetTokens: BudgetTokensSchema.optional(),
+    format: z.enum(['json', 'text']).optional(),
+  })
+  .refine((args) => args.id || args.path, 'knowledge.lookup requires id or path')
+
 const DocSearchArgsSchema = z.object({
   term: z.string().min(1),
   limit: z.number().int().positive().max(100).optional(),
+  agent: z.boolean().optional(),
+  mode: z.enum(['discovery', 'editing', 'debugging', 'documentation']).optional(),
+  contextBudgetTokens: z.number().int().positive().max(1_000_000).optional(),
 })
 
 const RetrieverQueryArgsSchema = z.object({
@@ -176,9 +241,9 @@ const DocGetArgsSchema = z
   .refine((args) => args.id || args.path, 'doc.get requires id or path')
 
 const WorkflowRunArgsSchema = z.object({ runId: z.string().min(1).optional() })
-const DiagnosticsArgsSchema = z.object({ status: z.string().min(1).optional(), severity: z.string().min(1).optional() })
+const DiagnosticsArgsSchema = z.object({ status: z.string().min(1).optional(), severity: z.string().min(1).optional(), format: z.enum(['diagnostic', 'finding']).optional() })
 const RelationsArgsSchema = z.object({ kind: z.string().min(1).optional(), limit: z.number().int().positive().max(500).optional() })
-const ProposalsArgsSchema = z.object({ action: z.enum(['list', 'propose-links', 'propose-normalize', 'suggest', 'approve', 'apply']).optional(), proposalHash: z.string().min(1).optional(), artifactPath: z.string().min(1).optional(), approvedBy: z.string().min(1).optional(), proposal: z.unknown().optional() })
+const ProposalsArgsSchema = z.object({ action: z.enum(['list', 'propose-links', 'propose-normalize', 'suggest', 'approve', 'apply', 'enrich-list', 'enrich-approve', 'enrich-reject']).optional(), proposalHash: z.string().min(1).optional(), artifactPath: z.string().min(1).optional(), approvedBy: z.string().min(1).optional(), proposal: z.unknown().optional(), proposalId: z.string().min(1).optional(), reason: z.string().max(1_024).optional() })
 
 const parseToolArgs = <T>(tool: string, schema: z.ZodType<T>, value: unknown): T => {
   try {
@@ -279,21 +344,37 @@ export const handleMcpRequest = (ctx: McpContext, request: JsonRpcRequest): unkn
     const args = asRecord(params.arguments)
     if (typeof name !== 'string') throw new Error('MCP tools/call requires a tool name.')
     assertMcpToolEnabled(ctx, name)
-    const index = () => ctx.loadIndex?.() ?? loadDocBridgeIndex(ctx.root, ctx.config)
+    const index = () => ctx.loadIndex?.() ?? loadFreshDocBridgeIndex(ctx.root, ctx.config)
 
     if (name === 'handoff.resolve') {
       const parsed = parseToolArgs('handoff.resolve', HandoffResolveArgsSchema, args)
-      return textResult(
-        runQuery(index(), ctx.config, {
-          kind: parsed.kind === 'package' ? 'package' : 'ownership',
-          id: parsed.id,
-          agent: true,
-        }),
-      )
+      const loaded = index()
+      const handoff = runQuery(loaded, ctx.config, {
+        kind: parsed.kind === 'package' ? 'package' : 'ownership',
+        id: parsed.id,
+        agent: true,
+      }, { root: ctx.root })
+      // The payload is the handoff it always was; a declared budget adds `budget` and may shed `related` and the summary note.
+      return textResult(parsed.budgetTokens === undefined ? handoff : budgetedHandoff(loaded, handoff as AgentHandoffV1, parsed.budgetTokens))
+    }
+
+    if (name === 'knowledge.search') {
+      const { format, ...parsed } = parseToolArgs('knowledge.search', KnowledgeSearchArgsSchema, args)
+      const response = knowledgeSearch(index(), parsed)
+      return textResult(format === 'text' ? formatKnowledgeSearchText(response) : response)
+    }
+
+    if (name === 'knowledge.lookup') {
+      const { format, ...parsed } = parseToolArgs('knowledge.lookup', KnowledgeLookupArgsSchema, args)
+      // Diagnostics come from the latest workflow run when there is one; a repository never checked still gets its lookup.
+      const report = () => { try { return workflowReport(ctx) } catch { return undefined } }
+      const response = knowledgeLookup(index(), ctx.config, parsed, { root: ctx.root, report })
+      return textResult(format === 'text' ? formatKnowledgeLookupText(response) : response)
     }
 
     if (name === 'doc.search') {
       const parsed = parseToolArgs('doc.search', DocSearchArgsSchema, args)
+      if (parsed.agent) return textResult(runQuery(index(), ctx.config, { kind: 'search', term: parsed.term, agent: true, ...(parsed.mode === undefined ? {} : { mode: parsed.mode }), ...(parsed.contextBudgetTokens === undefined ? {} : { contextBudgetTokens: parsed.contextBudgetTokens }) }))
       return textResult(searchIndex(index(), parsed.term, parsed.limit ?? 20))
     }
 
@@ -342,6 +423,8 @@ export const handleMcpRequest = (ctx: McpContext, request: JsonRpcRequest): unkn
       const diagnostics = workflowReport(ctx).diagnostics.filter((diagnostic) =>
         (!parsed.status || diagnostic.status === parsed.status) && (!parsed.severity || diagnostic.severity === parsed.severity),
       )
+      // `finding` is the ecosystem shape; the filters above still speak the internal vocabulary.
+      if (parsed.format === 'finding') return textResult(redactValue({ reportHash: workflowReport(ctx).contentHash, findings: findingsFromDiagnostics(diagnostics) }))
       return textResult(redactValue({ reportHash: workflowReport(ctx).contentHash, diagnostics }))
     }
 
@@ -359,20 +442,32 @@ export const handleMcpRequest = (ctx: McpContext, request: JsonRpcRequest): unkn
     if (name === 'docbridge.proposals') {
       const parsed = parseToolArgs('docbridge.proposals', ProposalsArgsSchema, args)
       const run = (() => { try { return workflowRun(ctx) } catch { return undefined } })()
+      // KR-10: enrichment proposals share this tool; a decision goes through the ecosystem approval gate.
+      if (parsed.action === 'enrich-list') return textResult(redactValue({ ...(run ? { runId: run.runId } : {}), enrichment: listEnrichment(ctx.root) ?? null }))
+      if (parsed.action === 'enrich-approve' || parsed.action === 'enrich-reject') {
+        if (!parsed.proposalId) throw new Error(`docbridge.proposals ${parsed.action} requires proposalId`)
+        const proposalId = parsed.proposalId
+        return (async () => {
+          const snapshot = (() => { try { return workflowSnapshot(ctx) } catch { return undefined } })()
+          const decided = await decideEnrichment({ root: ctx.root, proposalId, decision: parsed.action === 'enrich-approve' ? 'approved' : 'rejected', by: parsed.approvedBy ?? 'human', ...(parsed.reason ? { reason: parsed.reason } : {}), ...(snapshot ? { snapshot } : {}) })
+          return textResult(redactValue({ ...(run ? { runId: run.runId } : {}), approvalId: decided.approvalId, entry: decided.entry, overlayHash: decided.overlay.contentHash }))
+        })()
+      }
       if (!parsed.action || parsed.action === 'list') {
         let proposal: FixProposalV1 | undefined
         try { proposal = readSavedProposal(ctx, undefined) } catch { proposal = undefined }
         return textResult(redactValue({ ...(run ? { runId: run.runId } : {}), proposals: proposal ? [proposal] : [] }))
       }
       if (parsed.action === 'suggest') {
-        return loadRegistryAgentRunner(ctx.root, ctx.config).then(async (runner) => {
+        return (async () => {
+          const runner = ctx.config.intelligence?.registry?.cli ? undefined : await loadRegistryAgentRunner(ctx.root, ctx.config)
           const snapshot = workflowSnapshot(ctx)
           const report = workflowReport(ctx)
-          const adapter = createRegistryAgentAdapter(ctx.root, ctx.config, runner)
+          const adapter = createRegistryAgentAdapter(ctx.root, ctx.config, ctx.config.intelligence?.registry?.cli ? undefined : runner)
           const proposal = await adapter.run(snapshot, report)
           const savedPath = persistRegistryAgentProposal(workflowStateDir(ctx), proposal)
           return textResult(redactValue({ ...(run ? { runId: run.runId } : {}), proposal, proposalPath: savedPath }))
-        })
+        })()
       }
       const discovered = discoverRepository({ root: ctx.root, config: ctx.config })
       const options = { baseRevision: discovered.sourceRevision, configurationHash: sha256NormalizedV1(ctx.config), ...(ctx.config.project?.name ? { projectName: ctx.config.project.name } : {}) }

package/src/metrics/benchmark.ts

@@ -166,6 +166,27 @@ export const measureAgentEfficiency = (observation: AgentEfficiencyObservation)
   contextReduction: observation.corpusBytes > 0 ? 1 - (percentile95(observation.responseBytes) / observation.corpusBytes) : 0,
 })
 
+export type AgentTaskEfficiencyObservation = {
+  readonly correct: boolean
+  readonly latencyMs: number
+  readonly responseBytes: number
+  readonly estimatedTokens: number
+}
+
+export const measureAgentTaskEfficiency = (observations: readonly AgentTaskEfficiencyObservation[]) => {
+  const correct = observations.filter((observation) => observation.correct)
+  return {
+    taskCount: observations.length,
+    correctTaskCount: correct.length,
+    correctnessRate: ratio(correct.length, observations.length),
+    latencyP95Ms: percentile95(observations.map((observation) => observation.latencyMs)),
+    responseBytesP95: percentile95(observations.map((observation) => observation.responseBytes)),
+    estimatedTokensP95: percentile95(observations.map((observation) => observation.estimatedTokens)),
+    tokensToCorrectAnswerP95: correct.length ? percentile95(correct.map((observation) => observation.estimatedTokens)) : null,
+    timeToCorrectAnswerP95Ms: correct.length ? percentile95(correct.map((observation) => observation.latencyMs)) : null,
+  }
+}
+
 export const formatBenchmarkText = (result: BenchmarkResult): string => [
   `Precision: entities ${result.quality.entities.precision.toFixed(3)}, relations ${result.quality.relations.precision.toFixed(3)}, findings ${result.quality.findings.precision.toFixed(3)}`,
   `Recall: entities ${result.quality.entities.recall.toFixed(3)}, relations ${result.quality.relations.recall.toFixed(3)}, findings ${result.quality.findings.recall.toFixed(3)}`,

package/src/parity/check.ts

@@ -0,0 +1,309 @@
+import { existsSync, readFileSync } from 'node:fs'
+import { resolve } from 'node:path'
+
+import { z } from 'zod'
+
+import { contentHashForArtifactV1, sha256NormalizedV1 } from '../index-builder/content-hash.js'
+import { redactSecrets } from '../safety/repository.js'
+import {
+  claimPattern,
+  claimSurfaces,
+  exceptionFor,
+  renderClaim,
+  type PublicClaim,
+  type PublicClaimsV1,
+} from './claims.js'
+import { resolveClaim, type ResolveContext } from './resolve.js'
+
+/**
+ * Compare what this repository says in public with what it can prove.
+ *
+ * The four outcomes are kept apart on purpose, because they need different actions. `stale` means a
+ * surface states a value the repository has moved past — someone edits one line. `missing` means a
+ * surface that promised to carry the claim does not. `contradiction` means two public surfaces
+ * disagree with each other, which is the one an agent cannot resolve on its own and the reason this
+ * check exists. `not-analyzed` means the claim could not be resolved at all: reported, never
+ * counted as a pass.
+ *
+ * The report is publication-safe by construction. It carries claim ids, repository-relative surface
+ * paths, line numbers, the two values, and a bounded excerpt with secrets redacted — never a
+ * document's contents, never an absolute path.
+ */
+
+export const PUBLIC_PARITY_SCHEMA_VERSION = 1 as const
+export const PARITY_EXCERPT_LIMIT = 160
+
+const hash = z.string().regex(/^[a-f0-9]{64}$/)
+
+export const PARITY_CODES = ['PARITY_STALE', 'PARITY_MISSING', 'PARITY_CONTRADICTION', 'PARITY_NOT_ANALYZED'] as const
+export type ParityCode = (typeof PARITY_CODES)[number]
+
+const ParityFindingSchema = z
+  .object({
+    id: hash,
+    code: z.enum(PARITY_CODES),
+    claimId: z.string().min(1).max(64),
+    owner: z.string().min(1).max(128),
+    severity: z.enum(['error', 'warn', 'info']),
+    /** False when an exception accepted it. The reason travels with the finding, not in a comment. */
+    blocking: z.boolean(),
+    surface: z.string().max(512).optional(),
+    line: z.number().int().positive().optional(),
+    stated: z.string().max(256).optional(),
+    canonical: z.string().max(256).optional(),
+    message: z.string().min(1).max(1_024),
+    remediation: z.string().min(1).max(1_024),
+    excerpt: z.string().max(PARITY_EXCERPT_LIMIT).optional(),
+    acceptedReason: z.string().max(512).optional(),
+  })
+  .strict()
+
+export type ParityFinding = z.infer<typeof ParityFindingSchema>
+
+export const PublicParityReportV1Schema = z
+  .object({
+    type: z.literal('public-parity-report'),
+    schemaVersion: z.literal(PUBLIC_PARITY_SCHEMA_VERSION),
+    contentHash: hash,
+    contentHashAlgo: z.literal('sha256-normalized-v1'),
+    project: z.object({ name: z.string().min(1).max(128) }).strict(),
+    sourceRevision: z.string().min(1).max(128),
+    sourceRevisionKind: z.enum(['git', 'content']),
+    registryVersion: z.string().min(1).max(64),
+    registryHash: hash,
+    status: z.enum(['pass', 'needs-review', 'blocked']),
+    metrics: z
+      .object({
+        claims: z.number().int().nonnegative(),
+        surfaces: z.number().int().nonnegative(),
+        matched: z.number().int().nonnegative(),
+        stale: z.number().int().nonnegative(),
+        missing: z.number().int().nonnegative(),
+        contradictions: z.number().int().nonnegative(),
+        notAnalyzed: z.number().int().nonnegative(),
+        accepted: z.number().int().nonnegative(),
+        blocking: z.number().int().nonnegative(),
+      })
+      .strict(),
+    findings: z.array(ParityFindingSchema).max(10_000),
+    /** Surfaces the registry names that do not exist in this checkout. */
+    missingSurfaces: z.array(z.string().max(512)).max(64),
+    limitations: z.array(z.string().min(1).max(512)).max(32),
+  })
+  .strict()
+
+export type PublicParityReportV1 = z.infer<typeof PublicParityReportV1Schema>
+
+export type CheckParityOptions = ResolveContext & {
+  readonly registry: PublicClaimsV1
+  readonly project: { readonly name: string }
+  readonly sourceRevision: string
+  readonly sourceRevisionKind: 'git' | 'content'
+  /** File contents by surface path. Defaults to reading under `root`. */
+  readonly readSurface?: (path: string) => string | undefined
+}
+
+type Occurrence = { readonly surface: string; readonly line: number; readonly stated: string; readonly excerpt: string }
+
+const findingId = (parts: Record<string, unknown>): string => sha256NormalizedV1(parts)
+
+const excerptOf = (line: string): string => {
+  const collapsed = redactSecrets(line.trim()).replace(/\s+/g, ' ')
+  return collapsed.length <= PARITY_EXCERPT_LIMIT ? collapsed : `${collapsed.slice(0, PARITY_EXCERPT_LIMIT - 1)}…`
+}
+
+/**
+ * Every occurrence of a claim in one surface, with the line it sits on.
+ *
+ * A `cli-command` claim has no value to extract: the command either appears or it does not, and
+ * the canonical value is the command itself. Everything else is read through the claim's template
+ * for that surface, so one fact stated two ways is still one claim.
+ */
+const occurrences = (claim: PublicClaim, surface: string, content: string): readonly Occurrence[] => {
+  const found: Occurrence[] = []
+  const lines = content.split('\n')
+  for (const [index, line] of lines.entries()) {
+    if (claim.evidence.kind === 'cli-command') {
+      if (line.includes(claim.evidence.command)) {
+        found.push({ surface, line: index + 1, stated: claim.evidence.command, excerpt: excerptOf(line) })
+      }
+      continue
+    }
+    // A fresh pattern per line: a global regex carries lastIndex between calls.
+    for (const match of line.matchAll(claimPattern(claim, surface))) {
+      const stated = match[1]
+      if (stated === undefined) continue
+      found.push({ surface, line: index + 1, stated, excerpt: excerptOf(line) })
+    }
+  }
+  return found
+}
+
+export const checkPublicParity = (options: CheckParityOptions): PublicParityReportV1 => {
+  const { registry } = options
+  const read = options.readSurface ?? ((path: string): string | undefined => {
+    const absolute = resolve(options.root, path)
+    return existsSync(absolute) ? readFileSync(absolute, 'utf8') : undefined
+  })
+
+  const surfaces = claimSurfaces(registry)
+  const contents = new Map<string, string | undefined>(surfaces.map((surface) => [surface, read(surface)]))
+  const missingSurfaces = surfaces.filter((surface) => contents.get(surface) === undefined)
+
+  const findings: ParityFinding[] = []
+  const limitations: string[] = []
+  let matched = 0
+
+  for (const claim of [...registry.claims].sort((a, b) => a.claimId.localeCompare(b.claimId))) {
+    const resolved = resolveClaim(claim, options)
+    const declared = [...claim.required, ...(claim.optional ?? [])]
+
+    if (resolved.status === 'not-analyzed') {
+      findings.push({
+        id: findingId({ code: 'PARITY_NOT_ANALYZED', claimId: claim.claimId }),
+        code: 'PARITY_NOT_ANALYZED',
+        claimId: claim.claimId,
+        owner: claim.owner,
+        severity: 'warn',
+        blocking: false,
+        message: `${claim.statement} could not be resolved: ${resolved.reason}`,
+        remediation: claim.remediation,
+      })
+      limitations.push(`${claim.claimId}: ${resolved.reason}`)
+      continue
+    }
+
+    const stated = new Map<string, readonly Occurrence[]>()
+    for (const surface of declared) {
+      const content = contents.get(surface)
+      if (content === undefined) continue
+      stated.set(surface, occurrences(claim, surface, content))
+    }
+
+    /*
+     * A contradiction is about the surfaces agreeing with each other, so it is decided over the
+     * whole claim rather than per surface: two public pages stating different numbers is a finding
+     * even when neither of them matches the repository.
+     */
+    const distinct = [...new Set([...stated.values()].flat().map((entry) => entry.stated))].sort()
+    if (distinct.length > 1) {
+      findings.push({
+        id: findingId({ code: 'PARITY_CONTRADICTION', claimId: claim.claimId, distinct }),
+        code: 'PARITY_CONTRADICTION',
+        claimId: claim.claimId,
+        owner: claim.owner,
+        severity: 'error',
+        blocking: true,
+        canonical: resolved.value,
+        message: `Public surfaces state ${distinct.join(' and ')} for ${claim.statement.toLowerCase()}; the repository says ${resolved.value}.`,
+        remediation: claim.remediation,
+      })
+    }
+
+    for (const surface of declared) {
+      const content = contents.get(surface)
+      if (content === undefined) continue
+      const here = stated.get(surface) ?? []
+      const exception = exceptionFor(registry, claim.claimId, surface)
+      const accepted = exception !== undefined
+
+      if (!here.length) {
+        if (!claim.required.includes(surface)) continue
+        findings.push({
+          id: findingId({ code: 'PARITY_MISSING', claimId: claim.claimId, surface }),
+          code: 'PARITY_MISSING',
+          claimId: claim.claimId,
+          owner: claim.owner,
+          severity: accepted ? 'info' : claim.severity,
+          blocking: !accepted && claim.severity === 'error',
+          surface,
+          canonical: resolved.value,
+          message: `${surface} does not state ${claim.statement.toLowerCase()}`,
+          remediation: `Add "${renderClaim(claim, resolved.value, surface)}" to ${surface}, or record an exception with a reason.`,
+          ...(accepted ? { acceptedReason: exception.reason } : {}),
+        })
+        continue
+      }
+
+      for (const occurrence of here) {
+        if (occurrence.stated === resolved.value) {
+          matched += 1
+          continue
+        }
+        findings.push({
+          id: findingId({ code: 'PARITY_STALE', claimId: claim.claimId, surface, line: occurrence.line }),
+          code: 'PARITY_STALE',
+          claimId: claim.claimId,
+          owner: claim.owner,
+          severity: accepted ? 'info' : claim.severity,
+          blocking: !accepted && claim.severity === 'error',
+          surface,
+          line: occurrence.line,
+          stated: occurrence.stated,
+          canonical: resolved.value,
+          message: `${surface}:${occurrence.line} states ${occurrence.stated} where the repository says ${resolved.value}.`,
+          remediation: claim.remediation,
+          excerpt: occurrence.excerpt,
+          ...(accepted ? { acceptedReason: exception.reason } : {}),
+        })
+      }
+    }
+  }
+
+  for (const surface of missingSurfaces) {
+    limitations.push(`${surface} is named by the registry but absent from this checkout.`)
+  }
+
+  findings.sort((a, b) => a.claimId.localeCompare(b.claimId) || a.code.localeCompare(b.code) || (a.surface ?? '').localeCompare(b.surface ?? '') || (a.line ?? 0) - (b.line ?? 0))
+
+  const count = (code: ParityCode): number => findings.filter((finding) => finding.code === code).length
+  const blocking = findings.filter((finding) => finding.blocking).length
+  const payload = {
+    type: 'public-parity-report' as const,
+    schemaVersion: PUBLIC_PARITY_SCHEMA_VERSION,
+    contentHashAlgo: 'sha256-normalized-v1' as const,
+    project: { name: options.project.name },
+    sourceRevision: options.sourceRevision,
+    sourceRevisionKind: options.sourceRevisionKind,
+    registryVersion: registry.registryVersion,
+    registryHash: registry.contentHash,
+    status: blocking ? ('blocked' as const) : findings.length ? ('needs-review' as const) : ('pass' as const),
+    metrics: {
+      claims: registry.claims.length,
+      surfaces: surfaces.length - missingSurfaces.length,
+      matched,
+      stale: count('PARITY_STALE'),
+      missing: count('PARITY_MISSING'),
+      contradictions: count('PARITY_CONTRADICTION'),
+      notAnalyzed: count('PARITY_NOT_ANALYZED'),
+      accepted: findings.filter((finding) => finding.acceptedReason !== undefined).length,
+      blocking,
+    },
+    findings,
+    missingSurfaces,
+    limitations: [...limitations].sort(),
+  }
+  return PublicParityReportV1Schema.parse({ ...payload, contentHash: sha256NormalizedV1(payload) })
+}
+
+export const parsePublicParityReport = (input: unknown): PublicParityReportV1 => {
+  const report = PublicParityReportV1Schema.parse(input)
+  if (contentHashForArtifactV1(report) !== report.contentHash) throw new Error('Invalid public-parity report content hash.')
+  return report
+}
+
+export const formatPublicParityText = (report: PublicParityReportV1): readonly string[] => [
+  `Public parity: ${report.status} (registry ${report.registryVersion}, ${report.metrics.claims} claim(s) over ${report.metrics.surfaces} surface(s))`,
+  `Matched: ${report.metrics.matched}  Stale: ${report.metrics.stale}  Missing: ${report.metrics.missing}  Contradictions: ${report.metrics.contradictions}  Not analyzed: ${report.metrics.notAnalyzed}  Accepted: ${report.metrics.accepted}`,
+  ...report.findings.flatMap((finding) => {
+    const at = finding.surface ? ` ${finding.surface}${finding.line ? `:${finding.line}` : ''}` : ''
+    const mark = finding.blocking ? 'BLOCKING' : finding.acceptedReason ? 'accepted' : finding.severity
+    return [
+      `  [${mark}] ${finding.code}${at} (${finding.claimId}, owner ${finding.owner}): ${finding.message}`,
+      `    → ${finding.remediation}`,
+      ...(finding.acceptedReason ? [`    accepted: ${finding.acceptedReason}`] : []),
+    ]
+  }),
+  ...report.limitations.map((limitation) => `  limitation: ${limitation}`),
+  `Content hash: ${report.contentHash}`,
+]