@agentskit/doc-bridge 1.6.4 → 1.7.45

package/src/doctor/run-doctor.ts

@@ -52,17 +52,6 @@ const gradeForScore = (score: number): DoctorReport['grade'] => {
   return 'F'
 }
 
-const agentDocPaths = (index: DocBridgeIndexV1): Set<string> => {
-  const paths = new Set<string>()
-  for (const owner of Object.values(index.lookup?.ownership ?? {})) {
-    if (owner.agentDoc) paths.add(owner.agentDoc)
-  }
-  for (const handoff of Object.values(index.handoffs ?? {})) {
-    if (handoff.startHere) paths.add(handoff.startHere)
-  }
-  return paths
-}
-
 const computeScore = (coverage: DoctorCoverage): number => {
   let score = 0
 
@@ -166,7 +155,7 @@ export const runDoctor = (root: string, config: DocBridgeConfigV1): DoctorReport
   let index: DocBridgeIndexV1 | undefined
   let hasIndex = true
   let freshnessOk = false
-  let freshnessMessage = 'Index is fresh'
+  let freshnessMessage: string
 
   try {
     index = loadDocBridgeIndex(root, config)
@@ -191,8 +180,6 @@ export const runDoctor = (root: string, config: DocBridgeConfigV1): DoctorReport
   const missingHumanDoc = ownership.filter(([, owner]) => !owner.humanDoc).map(([id]) => id)
 
   const indexedPaths = new Set(index.knowledge.map((entry) => entry.path))
-  const expectedAgentDocs = agentDocPaths(index)
-  const unindexed = [...expectedAgentDocs].filter((path) => !indexedPaths.has(path))
 
   const corpusDocs = scanAgentCorpus(root, config).filter(
     (doc) => doc.path !== config.corpus.agent.index,
@@ -283,4 +270,4 @@ export const formatDoctorText = (report: DoctorReport): string[] => {
 
   lines.push('', 'Next actions', ...report.nextActions.map((action) => `  → ${action}`))
   return lines
-}
+}

package/src/federation/llms.ts

@@ -31,13 +31,25 @@ const defaultFetchText: FetchText = async (url) => {
   return res.text()
 }
 
+const httpUrl = (value: string): string | undefined => {
+  try {
+    const parsed = new URL(value)
+    if (parsed.protocol !== 'http:' && parsed.protocol !== 'https:') return undefined
+    if (parsed.username || parsed.password) return undefined
+    return parsed.href
+  } catch {
+    return undefined
+  }
+}
+
 const sourceText = async (
   root: string,
   source: string,
   fetchText: FetchText,
 ): Promise<string | null> => {
   try {
-    if (/^https?:\/\//.test(source)) return await fetchText(source)
+    const remote = httpUrl(source)
+    if (remote) return await fetchText(remote)
     const path = resolve(root, source)
     if (!existsSync(path)) return null
     return readFileSync(path, 'utf8')
@@ -52,34 +64,72 @@ const sameOrigin = (base: string, target: string): boolean => {
 }
 
 export const parseLlmsTxtLinks = (raw: string): { title: string; url: string; description?: string }[] => {
-  const links = [...raw.matchAll(/\[([^\]]+)\]\(([^)]+)\)(?::\s*([^\n]+))?/g)].map((match) => ({
-    title: match[1] ?? match[2] ?? 'link',
-    url: match[2] ?? '',
-    ...(match[3]?.trim() ? { description: match[3].trim() } : {}),
-  })).filter((link) => link.url)
-
-  for (const match of raw.matchAll(/(?:^|\s)(?:Raw|llms\.txt|Full bundle|ZIP bundle)?:?\s*(https?:\/\/\S+)/gi)) {
-    const url = match[1]?.replace(/[),.;]+$/, '')
-    if (url && !links.some((link) => link.url === url)) links.push({ title: slugFromPath(url), url })
+  const links: { title: string; url: string; description?: string }[] = []
+  for (const line of raw.split(/\r?\n/)) {
+    let cursor = 0
+    while (cursor < line.length) {
+      const open = line.indexOf('[', cursor)
+      if (open < 0) break
+      const titleEnd = line.indexOf(']', open + 1)
+      const urlStart = titleEnd < 0 ? -1 : line.indexOf('(', titleEnd + 1)
+      const urlEnd = urlStart < 0 ? -1 : line.indexOf(')', urlStart + 1)
+      if (titleEnd < 0 || urlStart !== titleEnd + 1 || urlEnd < 0) {
+        cursor = open + 1
+        continue
+      }
+      const title = line.slice(open + 1, titleEnd).trim()
+      const url = line.slice(urlStart + 1, urlEnd).trim()
+      const description = line.slice(urlEnd + 1).trim().replace(/^:\s*/, '')
+      if (url) links.push({ title: title || url, url, ...(description ? { description } : {}) })
+      cursor = urlEnd + 1
+    }
+
+    for (const token of line.split(/\s+/)) {
+      let end = token.length
+      while (end > 0 && '),.;:'.includes(token[end - 1] ?? '')) end -= 1
+      const url = token.slice(0, end)
+      if (!/^https?:\/\//i.test(url) || links.some((link) => link.url === url)) continue
+      links.push({ title: slugFromPath(url), url })
+    }
   }
   return links
 }
 
+const firstMatchingLine = (section: string, predicate: (line: string) => boolean): string | undefined =>
+  section.split(/\r?\n/).find((line) => predicate(line.trim()))?.trim()
+
+const sectionTitle = (section: string, sourceUrl: string): string => {
+  const titleLine = firstMatchingLine(section, (line) => line.startsWith('title:'))
+  if (titleLine) return titleLine.slice('title:'.length).trim()
+  const urlLine = firstMatchingLine(section, (line) => /^https?:\/\//i.test(line))
+  if (urlLine) {
+    try {
+      return new URL(urlLine).pathname.split('/').filter(Boolean).at(-1) ?? slugFromPath(sourceUrl)
+    } catch {
+      return slugFromPath(sourceUrl)
+    }
+  }
+  const heading = firstMatchingLine(section, (line) => line.startsWith('#'))
+  if (heading) return heading.replace(/^#+\s*/, '').trim()
+  return slugFromPath(sourceUrl)
+}
+
 export const chunksFromMarkdown = (
   property: string,
   raw: string,
   sourceUrl: string,
 ): DocBridgeRetrievedChunk[] => {
-  const searchable = raw.includes('\n==== ') ? raw : raw.replace(/^---\n[\s\S]*?\n---\n?/, '')
+  const frontmatterEnd = raw.startsWith('---\n') ? raw.indexOf('\n---', 4) : -1
+  const searchable = raw.includes('\n==== ')
+    ? raw
+    : frontmatterEnd >= 0
+      ? raw.slice(frontmatterEnd + '\n---'.length).replace(/^\n/, '')
+      : raw
   const sections = searchable.includes('\n==== ')
     ? searchable.split(/\n====\s+/).filter((section) => section.trim())
     : searchable.split(/\n(?=##?\s+)/)
   return sections.map((section, index) => {
-    const title =
-      /^title:\s*(.+)$/m.exec(section)?.[1]?.trim() ??
-      /^https?:\/\/\S+\/([^/\s]+)$/m.exec(section)?.[1]?.trim() ??
-      /^#+\s+(.+)$/m.exec(section)?.[1]?.trim() ??
-      slugFromPath(sourceUrl)
+    const title = sectionTitle(section, sourceUrl)
     const id = slugFromPath(title.toLowerCase().replace(/[^a-z0-9]+/g, '-').replace(/^-|-$/g, '')) || `${index}`
     return {
       chunkKey: `${property}:federated:${id}`,
@@ -112,10 +162,12 @@ export const loadFederatedChunks = async (
     chunks.push(...chunksFromMarkdown(source.id, llms, source.llmsTxt))
     const links = parseLlmsTxtLinks(llms)
     for (const link of links) {
-      const url = !/^https?:\/\//.test(link.url) && source.rawBaseUrl
-        ? `${source.rawBaseUrl.replace(/\/$/, '')}/${link.url.replace(/^\//, '')}`
-        : link.url
-      if (!/\.(md|txt)(?:$|\?)/.test(url)) continue
+      const linkUrl = httpUrl(link.url)
+      const baseUrl = source.rawBaseUrl ? httpUrl(source.rawBaseUrl) : undefined
+      const url = linkUrl ?? (baseUrl ? new URL(link.url, baseUrl).href : link.url)
+      let pathname = url
+      try { pathname = new URL(url).pathname } catch { /* local source */ }
+      if (!/\.(md|txt)$/i.test(pathname)) continue
       if (!sameOrigin(source.llmsTxt, url)) continue
       const raw = await sourceText(root, url, fetchText)
       if (raw) chunks.push(...chunksFromMarkdown(source.id, raw, url))

package/src/fixes/proposals.ts

@@ -1,4 +1,4 @@
-import { existsSync, readdirSync, readFileSync, realpathSync, renameSync, statSync, unlinkSync, writeFileSync } from 'node:fs'
+import { existsSync, readdirSync, readFileSync, realpathSync, renameSync, unlinkSync, writeFileSync } from 'node:fs'
 import { basename, dirname, extname, join, relative, resolve, sep } from 'node:path'
 
 import { contentHashForArtifactV1, sha256NormalizedV1 } from '../index-builder/content-hash.js'
@@ -99,8 +99,9 @@ export const createArtifactNormalizationProposal = (root: string, artifactPath:
   const projectRoot = realpathSync.native(resolve(root))
   const path = artifactPath.split(sep).join('/')
   const absolute = containedPath(projectRoot, path)
-  if (!absolute || !existsSync(absolute) || !statSync(absolute).isFile()) return undefined
-  const before = readFileSync(absolute, 'utf8')
+  if (!absolute) return undefined
+  let before: string
+  try { before = readFileSync(absolute, 'utf8') } catch { return undefined }
   let after: string
   try { after = `${JSON.stringify(sortJson(JSON.parse(before) as unknown), null, 2)}\n` } catch { return undefined }
   return after === before ? undefined : makeProposal(projectRoot, options, [{ path: relative(projectRoot, absolute).split(sep).join('/'), before, after }], ['The artifact contains valid JSON.'], ['The artifact is valid canonical JSON with one trailing newline.'])

package/src/index-builder/human-adapters/fumadocs.ts

@@ -1,5 +1,5 @@
 import { existsSync, readFileSync } from 'node:fs'
-import { dirname, join } from 'node:path'
+import { join } from 'node:path'
 
 import { optionString, scanMarkdownDocs, type HumanAdapter } from './core.js'
 

package/src/index-builder/watch-index.ts

@@ -1,5 +1,5 @@
 import { existsSync, watch } from 'node:fs'
-import { dirname, join, resolve } from 'node:path'
+import { dirname, resolve } from 'node:path'
 
 import type { DocBridgeConfigV1 } from '../config/schema.js'
 import { buildDocBridgeIndex } from './build-index.js'

package/src/index.ts

@@ -20,11 +20,13 @@ export {
   RulesConfigSchema,
   WorkflowConfigSchema,
   RepositorySafetyConfigSchema,
+  ReportConfigSchema,
   type RuleId,
   type RuleSeverity,
   type RulesConfig,
   type WorkflowConfig,
   type RepositorySafetyConfig,
+  type ReportConfig,
 } from './config/schema.js'
 
 export {
@@ -180,6 +182,33 @@ export {
   type GithubPrResult,
 } from './memory/github-pr.js'
 export { canonicalJsonV1, contentHashForArtifactV1, sha256NormalizedV1 } from './index-builder/content-hash.js'
+export {
+  ANALYZER_PLUGIN_CONTRACT_VERSION,
+  AnalyzerPluginManifestSchema,
+  AnalyzerPluginOutputSchema,
+  createAnalyzerRegistry,
+  type AnalyzerPlugin,
+  type AnalyzerPluginInput,
+  type AnalyzerPluginManifest,
+  type AnalyzerPluginOutput,
+  type AnalyzerRegistry,
+} from './plugins/contract.js'
+export {
+  BENCHMARK_SCHEMA_VERSION,
+  BenchmarkFixtureV1Schema,
+  benchmarkFixture,
+  compareBenchmarkSnapshots,
+  formatBenchmarkText,
+  measureAgentEfficiency,
+  measureBenchmark,
+  type AgentEfficiencyObservation,
+  type BenchmarkFixtureV1,
+  type BenchmarkObservation,
+  type BenchmarkResult,
+  type BenchmarkSetMetrics,
+  type BenchmarkSnapshot,
+  type BenchmarkSnapshotDiff,
+} from './metrics/benchmark.js'
 export {
   AgentProposalV1Schema,
   AffectedFileSchema,

package/src/lib/bounded-text.ts

@@ -1,4 +1,4 @@
-import { readFileSync, statSync } from 'node:fs'
+import { closeSync, fstatSync, openSync, readFileSync } from 'node:fs'
 
 export const MAX_DOCUMENT_BYTES = 4 * 1_024 * 1_024
 export const MAX_CORPUS_BYTES = 64 * 1_024 * 1_024
@@ -12,14 +12,19 @@ export const readBoundedText = (
 ): string => {
   const maxFileBytes = limits?.maxFileBytes ?? MAX_DOCUMENT_BYTES
   const maxCorpusBytes = limits?.maxCorpusBytes ?? MAX_CORPUS_BYTES
-  const stat = statSync(path)
-  if (!stat.isFile()) throw new Error(`Documentation path is not a regular file: ${path}`)
-  if (stat.size > maxFileBytes) {
-    throw new Error(`Documentation file exceeds the ${maxFileBytes} byte limit: ${path}`)
+  const fd = openSync(path, 'r')
+  try {
+    const stat = fstatSync(fd)
+    if (!stat.isFile()) throw new Error(`Documentation path is not a regular file: ${path}`)
+    if (stat.size > maxFileBytes) {
+      throw new Error(`Documentation file exceeds the ${maxFileBytes} byte limit: ${path}`)
+    }
+    if (budget.used + stat.size > maxCorpusBytes) {
+      throw new Error(`Documentation corpus exceeds the ${maxCorpusBytes} byte read budget.`)
+    }
+    budget.used += stat.size
+    return readFileSync(fd, 'utf8')
+  } finally {
+    closeSync(fd)
   }
-  if (budget.used + stat.size > maxCorpusBytes) {
-    throw new Error(`Documentation corpus exceeds the ${maxCorpusBytes} byte read budget.`)
-  }
-  budget.used += stat.size
-  return readFileSync(path, 'utf8')
 }

package/src/metrics/benchmark.ts

@@ -0,0 +1,176 @@
+import { z } from 'zod'
+
+export const BENCHMARK_SCHEMA_VERSION = 1 as const
+
+const stringList = z.array(z.string().min(1).max(512)).max(100_000)
+const benchmarkSets = z.object({
+  entities: stringList.default([]),
+  relations: stringList.default([]),
+  findings: stringList.default([]),
+}).strict()
+
+export const BenchmarkFixtureV1Schema = z.object({
+  schemaVersion: z.literal(BENCHMARK_SCHEMA_VERSION),
+  supported: benchmarkSets,
+  excluded: benchmarkSets.optional(),
+}).strict()
+
+export type BenchmarkFixtureV1 = z.infer<typeof BenchmarkFixtureV1Schema>
+
+export type BenchmarkObservation = {
+  readonly entities: readonly string[]
+  readonly relations: readonly string[]
+  readonly findings: readonly string[]
+  readonly evidenced?: readonly string[]
+  readonly findingCategories?: Readonly<Record<string, number>>
+}
+
+export type BenchmarkSetMetrics = {
+  readonly truePositives: number
+  readonly falsePositives: number
+  readonly falseNegatives: number
+  readonly precision: number
+  readonly recall: number
+  readonly duplicateCount: number
+}
+
+export type BenchmarkResult = {
+  readonly schemaVersion: typeof BENCHMARK_SCHEMA_VERSION
+  readonly quality: {
+    readonly entities: BenchmarkSetMetrics
+    readonly relations: BenchmarkSetMetrics
+    readonly findings: BenchmarkSetMetrics
+  }
+  readonly evidenceRatio: number
+  readonly findingDensity: number
+  readonly findingCategoryDistribution: Readonly<Record<string, number>>
+  readonly excludedCaseCount: number
+  readonly excludedCaseIds: Readonly<{ entities: number; relations: number; findings: number }>
+  readonly thresholds: { readonly precision: number; readonly recall: number }
+  readonly regressions: readonly string[]
+}
+
+const unique = (values: readonly string[]): Set<string> => new Set(values)
+const ratio = (numerator: number, denominator: number): number => denominator === 0 ? 1 : numerator / denominator
+
+const setMetrics = (
+  actualValues: readonly string[],
+  expectedValues: readonly string[],
+  excludedValues: readonly string[],
+): BenchmarkSetMetrics => {
+  const excluded = unique(excludedValues)
+  const activeActualValues = actualValues.filter((value) => !excluded.has(value))
+  const actual = unique(activeActualValues)
+  const expected = unique(expectedValues.filter((value) => !excluded.has(value)))
+  const truePositives = [...actual].filter((value) => expected.has(value)).length
+  const falsePositives = actual.size - truePositives
+  const falseNegatives = expected.size - truePositives
+  return {
+    truePositives,
+    falsePositives,
+    falseNegatives,
+    precision: ratio(truePositives, actual.size),
+    recall: ratio(truePositives, expected.size),
+    duplicateCount: activeActualValues.length - actual.size,
+  }
+}
+
+export const benchmarkFixture = (fixture: unknown): BenchmarkFixtureV1 => BenchmarkFixtureV1Schema.parse(fixture)
+
+export const measureBenchmark = (
+  observation: BenchmarkObservation,
+  fixture: BenchmarkFixtureV1,
+  thresholds: { readonly precision?: number; readonly recall?: number } = {},
+): BenchmarkResult => {
+  const excluded = fixture.excluded ?? { entities: [], relations: [], findings: [] }
+  const quality = {
+    entities: setMetrics(observation.entities, fixture.supported.entities, excluded.entities),
+    relations: setMetrics(observation.relations, fixture.supported.relations, excluded.relations),
+    findings: setMetrics(observation.findings, fixture.supported.findings, excluded.findings),
+  }
+  const actualEntities = unique(observation.entities)
+  const evidenced = unique(observation.evidenced ?? [])
+  const evidenceRatio = ratio([...actualEntities].filter((id) => evidenced.has(id)).length, actualEntities.size)
+  const findingDensity = ratio(unique(observation.findings).size, actualEntities.size)
+  const precisionThreshold = thresholds.precision ?? 0.95
+  const recallThreshold = thresholds.recall ?? 1
+  const regressions: string[] = []
+  for (const [name, metrics] of Object.entries(quality)) {
+    if (metrics.precision < precisionThreshold) regressions.push(`${name}.precision below ${precisionThreshold}`)
+    if (metrics.recall < recallThreshold) regressions.push(`${name}.recall below ${recallThreshold}`)
+  }
+  return {
+    schemaVersion: BENCHMARK_SCHEMA_VERSION,
+    quality,
+    evidenceRatio,
+    findingDensity,
+    findingCategoryDistribution: Object.fromEntries(Object.entries(observation.findingCategories ?? {}).sort(([a], [b]) => a.localeCompare(b))),
+    excludedCaseCount: excluded.entities.length + excluded.relations.length + excluded.findings.length,
+    excludedCaseIds: { entities: excluded.entities.length, relations: excluded.relations.length, findings: excluded.findings.length },
+    thresholds: { precision: precisionThreshold, recall: recallThreshold },
+    regressions,
+  }
+}
+
+export type BenchmarkSnapshot = Readonly<Record<string, string>>
+
+export type BenchmarkSnapshotDiff = {
+  readonly added: number
+  readonly removed: number
+  readonly unchanged: number
+  readonly reclassified: number
+  readonly unchangedEvidence: number
+}
+
+export const compareBenchmarkSnapshots = (
+  previous: BenchmarkSnapshot,
+  current: BenchmarkSnapshot,
+): BenchmarkSnapshotDiff => {
+  const ids = new Set([...Object.keys(previous), ...Object.keys(current)])
+  let added = 0
+  let removed = 0
+  let unchanged = 0
+  let reclassified = 0
+  let unchangedEvidence = 0
+  for (const id of ids) {
+    if (!(id in previous)) { added += 1; continue }
+    if (!(id in current)) { removed += 1; continue }
+    if (previous[id] === current[id]) unchanged += 1
+    else reclassified += 1
+    if (previous[id] === current[id]) unchangedEvidence += 1
+  }
+  return { added, removed, unchanged, reclassified, unchangedEvidence }
+}
+
+export type AgentEfficiencyObservation = {
+  readonly hits: number
+  readonly queries: number
+  readonly latencyMs: readonly number[]
+  readonly responseBytes: readonly number[]
+  readonly estimatedTokens: readonly number[]
+  readonly corpusBytes: number
+}
+
+const percentile95 = (values: readonly number[]): number => {
+  if (!values.length) return 0
+  const sorted = [...values].sort((a, b) => a - b)
+  return sorted[Math.min(sorted.length - 1, Math.ceil(sorted.length * 0.95) - 1)] ?? 0
+}
+
+export const measureAgentEfficiency = (observation: AgentEfficiencyObservation) => ({
+  hitRate: ratio(observation.hits, observation.queries),
+  latencyP95Ms: percentile95(observation.latencyMs),
+  responseBytesP95: percentile95(observation.responseBytes),
+  estimatedTokensP95: percentile95(observation.estimatedTokens),
+  corpusBytes: observation.corpusBytes,
+  contextReduction: observation.corpusBytes > 0 ? 1 - (percentile95(observation.responseBytes) / observation.corpusBytes) : 0,
+})
+
+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)}`,
+  `Evidence ratio: ${result.evidenceRatio.toFixed(3)}`,
+  `Finding density: ${result.findingDensity.toFixed(3)}`,
+  `Excluded cases: ${result.excludedCaseCount}`,
+  `Regressions: ${result.regressions.length ? result.regressions.join('; ') : 'none'}`,
+].join('\n')

package/src/plugins/contract.ts

@@ -0,0 +1,89 @@
+import { z } from 'zod'
+
+import { CoverageSchema, DiagnosticSchema, EntitySchema, RelationSchema, type Coverage, type KnowledgeDiagnostic, type KnowledgeEntity, type KnowledgeRelation } from '../schemas/knowledge.js'
+
+export const ANALYZER_PLUGIN_CONTRACT_VERSION = 1 as const
+
+export const AnalyzerPluginManifestSchema = z.object({
+  id: z.string().regex(/^[a-z][a-z0-9-]*$/).max(128),
+  version: z.string().min(1).max(64),
+  languages: z.array(z.string().min(1).max(64)).min(1).max(32),
+  frameworks: z.array(z.string().min(1).max(128)).max(32).default([]),
+  capabilities: z.array(z.string().min(1).max(128)).min(1).max(32),
+  knowledgeSchemaVersion: z.literal(1),
+  compatibility: z.object({ pipelineMajor: z.number().int().nonnegative() }).strict(),
+  unsupportedConstructs: z.array(z.string().min(1).max(256)).max(128).default([]),
+  resourceLimits: z.object({ maxFiles: z.number().int().positive().optional(), maxBytes: z.number().int().positive().optional() }).strict().default({}),
+}).strict()
+
+export type AnalyzerPluginManifest = z.infer<typeof AnalyzerPluginManifestSchema>
+
+export const AnalyzerPluginOutputSchema = z.object({
+  entities: z.array(EntitySchema).max(50_000).default([]),
+  relations: z.array(RelationSchema).max(100_000).default([]),
+  coverage: z.array(CoverageSchema).max(1_000).default([]),
+  diagnostics: z.array(DiagnosticSchema).max(100_000).default([]),
+}).strict()
+
+export type AnalyzerPluginOutput = z.infer<typeof AnalyzerPluginOutputSchema>
+
+export type AnalyzerPluginInput = {
+  readonly language: string
+  readonly framework?: string
+  readonly files: readonly { readonly path: string; readonly bytes: number }[]
+  readonly value?: unknown
+}
+
+export type AnalyzerPlugin = {
+  readonly manifest: AnalyzerPluginManifest
+  readonly analyze: (input: AnalyzerPluginInput) => Promise<unknown> | unknown
+}
+
+export type AnalyzerRegistry = {
+  readonly register: (plugin: AnalyzerPlugin) => void
+  readonly list: () => readonly AnalyzerPluginManifest[]
+  readonly analyze: (id: string, input: AnalyzerPluginInput) => Promise<AnalyzerPluginOutput>
+}
+
+const pipelineMajor = (version: string): number => Number.parseInt(version.split('.')[0] ?? '', 10)
+
+export const createAnalyzerRegistry = (options: { readonly pipelineVersion?: string; readonly maxPlugins?: number } = {}): AnalyzerRegistry => {
+  const plugins = new Map<string, AnalyzerPlugin>()
+  const pipeline = pipelineMajor(options.pipelineVersion ?? '1.0.0')
+  return {
+    register(plugin) {
+      const manifest = AnalyzerPluginManifestSchema.parse(plugin.manifest)
+      if (manifest.compatibility.pipelineMajor !== pipeline) throw new Error(`Analyzer plugin "${manifest.id}" requires pipeline major ${manifest.compatibility.pipelineMajor}; current pipeline is ${pipeline}.`)
+      if (plugins.has(manifest.id)) throw new Error(`Analyzer plugin "${manifest.id}" is already registered.`)
+      if (options.maxPlugins !== undefined && plugins.size >= options.maxPlugins) throw new Error(`Analyzer plugin limit ${options.maxPlugins} exceeded.`)
+      plugins.set(manifest.id, { ...plugin, manifest })
+    },
+    list() {
+      return [...plugins.values()].map((plugin) => plugin.manifest).sort((a, b) => a.id.localeCompare(b.id))
+    },
+    async analyze(id, input) {
+      const plugin = plugins.get(id)
+      if (!plugin) throw new Error(`Analyzer plugin "${id}" is not registered.`)
+      const { maxFiles, maxBytes } = plugin.manifest.resourceLimits
+      const bytes = input.files.reduce((total, file) => total + file.bytes, 0)
+      if (maxFiles !== undefined && input.files.length > maxFiles) throw new Error(`Analyzer plugin "${id}" file limit ${maxFiles} exceeded.`)
+      if (maxBytes !== undefined && bytes > maxBytes) throw new Error(`Analyzer plugin "${id}" byte limit ${maxBytes} exceeded.`)
+      try {
+        const output = AnalyzerPluginOutputSchema.parse(await plugin.analyze(input))
+        return {
+          ...output,
+          coverage: output.coverage.map((entry) => ({ ...entry, analyzer: plugin.manifest.id, analyzerVersion: plugin.manifest.version })),
+        }
+      } catch (error) {
+        return {
+          entities: [],
+          relations: [],
+          diagnostics: [],
+          coverage: [{ analyzer: plugin.manifest.id, analyzerVersion: plugin.manifest.version, scope: 'plugin', status: 'not-analyzed', reason: `Plugin failed safely: ${error instanceof Error ? error.message : String(error)}` }],
+        }
+      }
+    },
+  }
+}
+
+export type { Coverage, KnowledgeDiagnostic, KnowledgeEntity, KnowledgeRelation }