@agentskit/doc-bridge 1.7.44 → 1.9.0

package/src/retrieval/rank.ts

@@ -0,0 +1,383 @@
+import { foldAccents, hasSearchToken, searchTokens } from '../query/text.js'
+import type { Confidence, RetrievalEdge, RetrievalEntry, RetrievalIndexV1 } from '../schemas/retrieval-index.js'
+import { buildBm25Index, bm25Search, type Bm25Hit, type Bm25Index } from './bm25.js'
+import { weakerConfidence } from './project.js'
+
+/**
+ * Ranking over the retrieval projection.
+ *
+ * The score has named parts, and every part is reported when asked, because a ranking that
+ * cannot say why it put one record above another cannot be corrected: a wrong answer is then an
+ * opinion about weights rather than a bug with a line number. Lexical evidence is BM25 over the
+ * projected fields; identity boosts reward a query that names a thing rather than describes it;
+ * graph proximity rewards being next to what the query clearly found; canonicality rewards the
+ * page other pages point at; the audience prior is what `--agent` means. Priors multiply the
+ * lexical evidence rather than adding to it, so a favoured record still needs a real match.
+ */
+
+/** Turns a BM25 score into the same magnitude as the identity boosts below. */
+const BM25_SCALE = 50
+
+const EXACT_ID = 200
+const EXACT_PATH = 150
+const EXACT_SYMBOL = 150
+const DIRECTORY_MATCH = 120
+const TOKEN_ID = 120
+const TOKEN_PATH = 100
+const TOKEN_SYMBOL = 90
+const SHORT_ID_BONUS = 40
+/** A query this short is a name; a longer one is a sentence that happens to contain names. */
+const NAMING_QUERY_TOKENS = 2
+
+/**
+ * Proximity: a candidate one hop from something the query clearly found is probably what the
+ * query meant, or the place to read about it. Two hops is a weaker hint. Only the ten strongest
+ * lexical hits count as anchors — beyond that the "clearly found" premise no longer holds — and
+ * the boost is as strong as the anchor: being next to the best match is worth the full amount,
+ * being next to a marginal one worth a fraction, so a hub page that barely matched cannot lift
+ * everything it links to above the module that answers.
+ */
+const PROXIMITY_ANCHORS = 10
+const PROXIMITY_ONE_HOP = 30
+const PROXIMITY_TWO_HOPS = 12
+
+/**
+ * Canonicality: log-scaled PageRank, so a page every document links to earns a bounded bonus and
+ * the long tail of leaf pages earns close to nothing. Scaled by the corpus size, because a
+ * PageRank is a share of one and only means something relative to the uniform 1/N.
+ */
+const CANONICALITY_SCALE = 4
+
+/** The `--agent` prior: documentation written for an agent answers an agent's question first. */
+const AUDIENCE_FIT = 25
+
+/**
+ * Accepted agent signals: bounded influence.
+ *
+ * An entry's signal is a share in 0..1 of this weight, and the weight is 15% of the exact-id
+ * boost. That is the whole contract: an accepted rank hint or canonical marker can reorder
+ * near-ties among lexical hits, and can never lift an entry past one the query named exactly.
+ * Signals apply to lexical hits only, like every other tie-breaker.
+ */
+export const ACCEPTED_SIGNALS_SHARE = 0.15
+export const ACCEPTED_SIGNALS_WEIGHT = Math.round(EXACT_ID * ACCEPTED_SIGNALS_SHARE)
+
+const CURATED_FACTOR = 1.15
+const OWNERSHIP_FACTOR = 1.1
+const ROUTE_TITLE_FACTOR = 1.6
+const CHANGE_INTENT_FACTOR = 1.4
+const CHANGE_WITHOUT_INTENT_FACTOR = 0.15
+const KIND_FACTOR = 1.15
+const PARTIAL_ID_FACTOR = 1.2
+
+export const RELEVANCE_FLOOR = 1 / 3
+
+const PACKAGE_INTENT =
+  /\b(package|module|pkg|edit|change|where|owns?|ownership|handoff|start)\b|\b(?:pacote|pacotes|modulo|modulos|onde|quem|dono|donos|responsavel|responsaveis|comec\w*|inici\w*|edit\w*|mud\w*|alter\w*)/i
+const CHANGE_INTENT =
+  /\b(change|edit|modify|update|fix|migrate|replace)\b|\b(?:alter\w*|mud\w*|modific\w*|edit\w*|atualiz\w*|corrig\w*|migr\w*|substitu\w*|troc\w*)/i
+const SYMBOL_SHAPED = /[a-z0-9][A-Z]|^[A-Za-z_$][A-Za-z0-9_$]{2,}$/
+const PATH_SHAPED = /\/|\.[A-Za-z]{1,4}$/
+
+export type ScoreComponents = {
+  readonly lexical: number
+  readonly prior: number
+  readonly exactId: number
+  readonly exactPath: number
+  readonly exactSymbol: number
+  readonly graphProximity: number
+  readonly canonicality: number
+  readonly audienceFit: number
+  readonly acceptedAgentSignals: number
+}
+
+export type RankExplanation = {
+  /** Query terms after the lexicon: what the ranker actually looked for. */
+  readonly terms: readonly string[]
+  /** Which terms matched in which field. */
+  readonly matched: Readonly<Record<string, readonly string[]>>
+  readonly components: ScoreComponents
+  /**
+   * The edge proximity found this result through. When nothing matched lexically it is the only
+   * reason the result is here; otherwise it is what the proximity component stands on.
+   */
+  readonly surfacedBy?: { readonly kind: string; readonly id: string; readonly confidence: Confidence; readonly hops: number }
+}
+
+export type RankedEntry = {
+  readonly entry: RetrievalEntry
+  readonly score: number
+  /**
+   * The entry's own confidence when the query matched it directly; when a relation alone
+   * surfaced it, the weaker of the entry and that relation — a result is as trustworthy as the
+   * least trustworthy step that produced it.
+   */
+  readonly confidence: Confidence
+  readonly explanation: RankExplanation
+}
+
+export type RankOptions = {
+  readonly limit?: number
+  /** The `--agent` prior: favour documentation written for an agent. */
+  readonly agent?: boolean
+  /** Per-entry accepted overlay signals (0..1), by entry id. Overrides the `agentSignal` the projection carries. */
+  readonly signals?: ReadonlyMap<string, number>
+  /**
+   * Results scoring below this share of the best score are dropped. The default spends context
+   * on nothing weak; a caller assembling a neighbourhood rather than an answer passes 0.
+   */
+  readonly floor?: number
+}
+
+const round = (value: number): number => Math.round(value * 1_000_000) / 1_000_000
+
+const pathBase = (path: string): string => foldAccents((path.split('/').pop() ?? '').replace(/\.[A-Za-z0-9]+$/, '').toLowerCase())
+
+const preferOwnership = (term: string): boolean => PACKAGE_INTENT.test(term) || /^(where|how).*(edit|change|package|module)/i.test(term)
+
+const titleCoversQuery = (title: string, tokens: readonly string[]): boolean =>
+  tokens.length > 1 && tokens.every((token) => hasSearchToken(foldAccents(title.toLowerCase()), token))
+
+const partialIdMatch = (id: string, tokens: readonly string[]): boolean => {
+  const idLower = foldAccents(id.toLowerCase())
+  return tokens.some(
+    (token) =>
+      idLower !== token &&
+      (idLower.startsWith(`${token}-`) || idLower.endsWith(`-${token}`) || (idLower.includes(token) && idLower.length <= token.length + 4)),
+  )
+}
+
+/** The names an entry answers to when the query is an identifier: its aliases and, for a route, its id. */
+const identifiers = (entry: RetrievalEntry): string[] =>
+  [...new Set([...entry.aliases, ...(entry.kind === 'intent' || entry.kind === 'change' ? [entry.id] : []), ...(entry.ownershipId ? [entry.ownershipId] : [])])].map((value) =>
+    foldAccents(value.toLowerCase()),
+  )
+
+type Identity = { readonly exactId: number; readonly exactPath: number; readonly exactSymbol: number }
+
+/**
+ * The query names the thing rather than describing it.
+ *
+ * A module is identified by its path and its exported symbols, a package or an area by its id and
+ * its aliases (an ownership id, a short name), a document by its filename. The whole query is
+ * checked before its tokens, so `src/mcp/server.ts` beats every record that merely mentions `mcp`.
+ */
+const identityBoost = (entry: RetrievalEntry, tokens: readonly string[], term: string): Identity => {
+  const ids = identifiers(entry)
+  const entityId = foldAccents(entry.id.toLowerCase())
+  const pathLower = foldAccents(entry.path.toLowerCase())
+  const termLower = foldAccents(term.toLowerCase().trim())
+  const base = pathBase(entry.path)
+  const symbols = new Set((entry.symbols ?? []).map((symbol) => foldAccents(symbol.toLowerCase())))
+  let exactId = 0
+  let exactPath = 0
+  let exactSymbol = 0
+
+  if (ids.includes(termLower) || entityId === termLower) exactId += EXACT_ID
+  if (base === termLower || pathLower === termLower) exactPath += EXACT_PATH
+  if (symbols.has(termLower)) exactSymbol += EXACT_SYMBOL
+  if (termLower && (pathLower.startsWith(`${termLower}/`) || pathLower.includes(`/${termLower}/`))) exactPath += DIRECTORY_MATCH
+
+  /*
+   * Per-token identity for filenames and symbols is for short queries: `search index` names
+   * `searchIndex`, and `bm25` names `bm25.ts`. A sentence does not name a file by containing one
+   * of its tokens — in "where are workflow transitions persisted", `transition` coinciding with an
+   * exported name is lexical evidence, which BM25 already weighs, not identity. An id or an alias
+   * is different: an ownership id is a name someone chose for a unit, and "integration setup auth"
+   * does name `auth`. Directory segments never count: an area or a package is named by the whole
+   * term, or by an alias it was given.
+   */
+  const file = entry.kind === 'document' || entry.kind === 'module'
+  const naming = tokens.length <= NAMING_QUERY_TOKENS
+  for (const token of tokens) {
+    if (ids.includes(token)) exactId += TOKEN_ID
+    if (naming && file && base === token) exactPath += TOKEN_PATH
+    if (naming && symbols.has(token)) exactSymbol += TOKEN_SYMBOL
+  }
+
+  // Prefer a short id when the query is the id: "core" should mean the core package.
+  const shortest = ids.filter((id) => tokens.includes(id)).sort((a, b) => a.length - b.length)[0]
+  if (shortest) exactId += Math.max(0, SHORT_ID_BONUS - shortest.length)
+
+  return { exactId, exactPath, exactSymbol }
+}
+
+/** A nudge toward the kind of record the query shape asks for. A prior, not a filter. */
+const priorFactor = (entry: RetrievalEntry, tokens: readonly string[], term: string, wantOwnership: boolean): number => {
+  const trimmed = term.trim()
+  const covered = titleCoversQuery(entry.title, tokens)
+  let factor = 1
+
+  if (entry.audience === 'agent' || entry.audience === 'human-and-agent') factor *= CURATED_FACTOR
+  if (identifiers(entry).some((id) => partialIdMatch(id, tokens))) factor *= PARTIAL_ID_FACTOR
+  if (entry.ownershipId && wantOwnership) factor *= OWNERSHIP_FACTOR
+  if ((entry.kind === 'intent' || entry.kind === 'change') && covered) factor *= ROUTE_TITLE_FACTOR
+  if (entry.kind === 'change') factor *= CHANGE_INTENT.test(term) ? CHANGE_INTENT_FACTOR : covered ? 1 : CHANGE_WITHOUT_INTENT_FACTOR
+
+  const oneWord = !/\s/.test(trimmed)
+  const looksLikeSymbol = oneWord && SYMBOL_SHAPED.test(trimmed)
+  const looksLikePath = oneWord && PATH_SHAPED.test(trimmed)
+  if ((looksLikeSymbol || looksLikePath) && entry.kind === 'module') factor *= KIND_FACTOR
+  if (!looksLikeSymbol && !looksLikePath && tokens.length >= 3 && entry.kind === 'document') factor *= KIND_FACTOR
+
+  return factor
+}
+
+type Prepared = {
+  readonly byId: ReadonlyMap<string, RetrievalEntry>
+  readonly bm25: Bm25Index
+  /** Undirected one-hop neighbourhood over documentation and import edges, by entry id. */
+  readonly neighbours: ReadonlyMap<string, readonly RetrievalEdge[]>
+  readonly entryCount: number
+}
+
+const prepared = new WeakMap<RetrievalIndexV1, Prepared>()
+
+/**
+ * Tokenising every entry is the expensive part of a search and gives the same result for every
+ * query against the same index, so it is done once per index object. The map is weak: nothing is
+ * retained once the caller drops the index.
+ */
+const prepare = (index: RetrievalIndexV1): Prepared => {
+  const cached = prepared.get(index)
+  if (cached) return cached
+  const neighbours = new Map<string, RetrievalEdge[]>()
+  const link = (from: string, edge: RetrievalEdge): void => {
+    const list = neighbours.get(from)
+    if (list) list.push(edge)
+    else neighbours.set(from, [edge])
+  }
+  for (const entry of index.entries) {
+    for (const edge of entry.graph.inbound) link(entry.id, edge)
+    for (const edge of entry.graph.outbound) link(entry.id, edge)
+  }
+  const value: Prepared = {
+    byId: new Map(index.entries.map((entry) => [entry.id, entry])),
+    bm25: buildBm25Index(index.entries.map((entry) => ({ ref: entry.id, fields: entry.fields })), index.weights, index.params),
+    neighbours,
+    entryCount: index.entries.length,
+  }
+  prepared.set(index, value)
+  return value
+}
+
+type Reach = { readonly hops: number; readonly via: RetrievalEdge; readonly anchorShare: number }
+
+/**
+ * What the strongest lexical hits are next to, within two hops.
+ *
+ * Nearest wins: an entry reachable in one hop from one anchor and two from another is one hop
+ * away. The edge recorded is the one that made the shortest reach, so the explanation names a
+ * real relation and the result's confidence can be no better than that relation's.
+ */
+const reachable = (ready: Prepared, anchors: readonly Bm25Hit[]): ReadonlyMap<string, Reach> => {
+  const reach = new Map<string, Reach>()
+  const anchored = new Set(anchors.map((anchor) => anchor.ref))
+  const best = anchors[0]?.score ?? 0
+  // Anchors are visited strongest first, so the first reach recorded is the strongest one.
+  for (const anchor of anchors) {
+    const anchorShare = best > 0 ? anchor.score / best : 0
+    for (const first of ready.neighbours.get(anchor.ref) ?? []) {
+      if (anchored.has(first.id)) continue
+      const known = reach.get(first.id)
+      if (!known || known.hops > 1) reach.set(first.id, { hops: 1, via: { kind: first.kind, id: anchor.ref, confidence: first.confidence }, anchorShare })
+      for (const second of ready.neighbours.get(first.id) ?? []) {
+        if (anchored.has(second.id) || second.id === anchor.ref) continue
+        if (!reach.has(second.id)) {
+          reach.set(second.id, { hops: 2, via: { kind: second.kind, id: first.id, confidence: weakerConfidence(first.confidence, second.confidence) }, anchorShare })
+        }
+      }
+    }
+  }
+  return reach
+}
+
+const canonicalityBoost = (pagerank: number, entryCount: number): number =>
+  pagerank > 0 && entryCount > 0 ? CANONICALITY_SCALE * Math.log1p(pagerank * entryCount) : 0
+
+/**
+ * Rank the projection against a query.
+ *
+ * Ordering is total: score descending, then an exact id match, then an ownership-backed entry,
+ * then id ascending — so two runs agree exactly and a tie never depends on insertion order.
+ * Results below a third of the best score are dropped: retrieval exists to spend fewer tokens.
+ */
+export const rankRetrieval = (index: RetrievalIndexV1, term: string, options: RankOptions = {}): RankedEntry[] => {
+  const tokens = searchTokens(term)
+  if (!tokens.length || !index.entries.length) return []
+  const ready = prepare(index)
+  const hits = bm25Search(ready.bm25, tokens)
+  const wantOwnership = preferOwnership(term)
+  const limit = options.limit ?? 20
+
+  const hitByRef = new Map<string, Bm25Hit>(hits.map((hit) => [hit.ref, hit]))
+  const reach = reachable(ready, hits.slice(0, PROXIMITY_ANCHORS))
+
+  // Candidates are every lexical hit plus what the strongest hits are next to.
+  const candidateIds = new Set<string>([...hitByRef.keys(), ...reach.keys()])
+  const ranked: RankedEntry[] = []
+
+  for (const id of candidateIds) {
+    const entry = ready.byId.get(id)
+    if (!entry) continue
+    const hit = hitByRef.get(id)
+    const near = reach.get(id)
+    const lexical = round((hit?.score ?? 0) * BM25_SCALE)
+    const prior = round(priorFactor(entry, tokens, term, wantOwnership))
+    const identity = identityBoost(entry, tokens, term)
+    const graphProximity = near ? round((near.hops === 1 ? PROXIMITY_ONE_HOP : PROXIMITY_TWO_HOPS) * near.anchorShare) : 0
+    const canonicality = round(canonicalityBoost(entry.graph.pagerank, ready.entryCount))
+    const audienceFit = options.agent && (entry.audience === 'agent' || entry.audience === 'human-and-agent') ? AUDIENCE_FIT : 0
+    const signal = Math.min(1, Math.max(0, options.signals?.get(id) ?? entry.agentSignal ?? 0))
+    const acceptedAgentSignals = round(signal * ACCEPTED_SIGNALS_WEIGHT)
+
+    /*
+     * A record nothing matched lexically is only here because of proximity. It earns proximity
+     * and nothing else: the query did not name it, and canonicality is a tie-breaker among
+     * answers, not an answer. Everything else scales from the lexical evidence.
+     */
+    const evidence = hit ? lexical * prior + identity.exactId + identity.exactPath + identity.exactSymbol : 0
+    const score = round(evidence + graphProximity + (hit ? canonicality + audienceFit + acceptedAgentSignals : 0))
+    if (score <= 0) continue
+
+    const components: ScoreComponents = {
+      lexical,
+      prior,
+      exactId: hit ? identity.exactId : 0,
+      exactPath: hit ? identity.exactPath : 0,
+      exactSymbol: hit ? identity.exactSymbol : 0,
+      graphProximity,
+      canonicality: hit ? canonicality : 0,
+      audienceFit: hit ? audienceFit : 0,
+      acceptedAgentSignals: hit ? acceptedAgentSignals : 0,
+    }
+    ranked.push({
+      entry,
+      score,
+      confidence: near && !hit ? weakerConfidence(entry.confidence, near.via.confidence) : entry.confidence,
+      explanation: {
+        terms: tokens,
+        matched: hit?.matched ?? {},
+        components,
+        ...(near ? { surfacedBy: { ...near.via, hops: near.hops } } : {}),
+      },
+    })
+  }
+
+  ranked.sort((a, b) => {
+    if (b.score !== a.score) return b.score - a.score
+    const aExact = a.explanation.components.exactId > 0 ? 1 : 0
+    const bExact = b.explanation.components.exactId > 0 ? 1 : 0
+    if (bExact !== aExact) return bExact - aExact
+    const aOwned = a.entry.ownershipId ? 1 : 0
+    const bOwned = b.entry.ownershipId ? 1 : 0
+    if (bOwned !== aOwned) return bOwned - aOwned
+    return a.entry.id.localeCompare(b.entry.id)
+  })
+
+  const best = ranked[0]?.score ?? 0
+  const floor = options.floor ?? RELEVANCE_FLOOR
+  const kept = best > 0 ? ranked.filter((item) => item.score >= best * floor) : ranked
+  return kept.slice(0, limit)
+}
+

package/src/retrieval/weights.ts

@@ -0,0 +1,39 @@
+import type { Bm25FieldWeights, Bm25Params } from './bm25.js'
+
+/**
+ * Which field an agent's query is most likely aiming at, in ranking order.
+ *
+ * These are a starting point, not a truth: they live in the index so a repository can retune
+ * retrieval from configuration, and a tuning change shows up as a changed artifact rather than a
+ * silent behaviour change. `title` sits at the top because a record is about what its title says;
+ * `aliases` carries the ids a record answers to; `body` sits at the bottom because a passing
+ * mention in prose is the weakest evidence a record is the answer.
+ */
+export const DEFAULT_SEARCH_WEIGHTS: Bm25FieldWeights = {
+  title: 4,
+  headings: 3,
+  symbols: 3,
+  path: 2,
+  aliases: 2,
+  summary: 2,
+  body: 1,
+}
+
+export const DEFAULT_SEARCH_PARAMS: Required<Bm25Params> = { k1: 1.2, b: 0.75 }
+
+/** Configured weights override the defaults field by field; an unknown field is ignored. */
+export const resolveSearchWeights = (configured?: Readonly<Record<string, number>>): Bm25FieldWeights => {
+  if (!configured) return DEFAULT_SEARCH_WEIGHTS
+  const merged: Record<string, number> = { ...DEFAULT_SEARCH_WEIGHTS }
+  for (const [field, weight] of Object.entries(configured)) {
+    if (field in DEFAULT_SEARCH_WEIGHTS) merged[field] = weight
+  }
+  return merged
+}
+
+export const resolveSearchParams = (
+  configured?: { readonly k1?: number | undefined; readonly b?: number | undefined },
+): Required<Bm25Params> => ({
+  k1: configured?.k1 ?? DEFAULT_SEARCH_PARAMS.k1,
+  b: configured?.b ?? DEFAULT_SEARCH_PARAMS.b,
+})

package/src/retriever/doc-bridge-retriever.ts

@@ -1,9 +1,37 @@
 import type { DocBridgeIndexV1 } from '../schemas/doc-bridge-index.js'
-import { searchIndex } from '../query/search.js'
+import { searchIndex, type SearchMatch } from '../query/search.js'
+
+/**
+ * Doc Bridge as a `Retriever`.
+ *
+ * The types below mirror `RetrievedDocument`, `RetrieverRequest` and `Retriever` from
+ * `@agentskit/core`, which is an optional peer: a published type that only resolves when an
+ * optional package is installed breaks a clean install. A test asserts assignability against the
+ * real package and runs the real hybrid retriever over this one, so a drift fails there rather
+ * than at a consumer.
+ */
+export type RetrievedDocument = {
+  readonly id: string
+  readonly content: string
+  readonly source?: string
+  readonly score?: number
+  readonly metadata?: Record<string, unknown>
+}
+
+export type RetrieverRequest = {
+  readonly query: string
+  readonly messages: readonly unknown[]
+}
+
+export type Retriever = {
+  readonly retrieve: (request: RetrieverRequest) => RetrievedDocument[] | Promise<RetrievedDocument[]>
+}
 
 export type DocBridgeRetrieverOptions = {
   readonly property?: string
   readonly limit?: number
+  /** The `--agent` prior. */
+  readonly agent?: boolean
 }
 
 export type DocBridgeRetrievedChunk = {
@@ -17,15 +45,13 @@ export type DocBridgeRetrievedChunk = {
   readonly score: number
 }
 
-export type DocBridgeRetriever = {
-  readonly retrieve: (
-    query: string,
-    options?: Pick<DocBridgeRetrieverOptions, 'limit'>,
-  ) => DocBridgeRetrievedChunk[]
+export type DocBridgeRetriever = Retriever & {
+  /** The original calling convention, kept: a query string and an optional limit. */
+  readonly retrieve: ((request: RetrieverRequest) => RetrievedDocument[]) &
+    ((query: string, options?: Pick<DocBridgeRetrieverOptions, 'limit'>) => RetrievedDocument[])
 }
 
-const chunkKey = (property: string, type: string, id: string): string =>
-  `${property}:${type}:${id}`
+const chunkKey = (property: string, type: string, id: string): string => `${property}:${type}:${id}`
 
 export const retrieveDocBridgeChunks = (
   index: DocBridgeIndexV1,
@@ -35,28 +61,87 @@ export const retrieveDocBridgeChunks = (
   const property = options.property ?? index.project?.name ?? 'local'
   const limit = options.limit ?? 8
 
-  return searchIndex(index, query, limit).map((match) => {
+  return searchIndex(index, query, limit, options.agent ? { agent: true } : {}).map((match) => {
     const knowledge = index.knowledge.find((entry) => entry.id === match.id && entry.path === match.path)
     const owner = index.lookup?.ownership?.[match.id]
     const type = match.type === 'ownership' ? 'ownership' : (knowledge?.type ?? match.type)
     const summary = match.summary ?? owner?.purpose
+    const title = knowledge?.title ?? index.projection?.entries.find((entry) => entry.id === match.entityId)?.title
     return {
       chunkKey: chunkKey(property, type, match.id),
       property,
       type,
       id: match.id,
       path: match.path,
-      ...(knowledge?.title ? { title: knowledge.title } : {}),
+      ...(title ? { title } : {}),
       ...(summary ? { summary } : {}),
       score: match.score,
     }
   })
 }
 
-export const createDocBridgeRetriever = (
+/**
+ * What a retrieved document's content is: the projected text, in the order a reader wants it.
+ *
+ * Title, then summary, then the search body — the same bounded text the ranker matched, so what
+ * a model reads is what the score was computed over. Without a projection the record has only
+ * its title and description, which is what the legacy index carried.
+ */
+const contentFor = (index: DocBridgeIndexV1, match: SearchMatch): string => {
+  const entry = match.entityId ? index.projection?.entries.find((item) => item.id === match.entityId) : undefined
+  if (entry) {
+    return [entry.title, entry.summary, entry.fields.body].filter((part): part is string => Boolean(part && part.trim())).join('\n\n')
+  }
+  const knowledge = index.knowledge.find((item) => item.id === match.id && item.path === match.path)
+  return [knowledge?.title ?? match.id, knowledge?.description ?? match.summary, knowledge?.body].filter((part): part is string => Boolean(part)).join('\n\n')
+}
+
+/**
+ * Rank the index and return the results as `RetrievedDocument`s.
+ *
+ * `metadata` carries what the ecosystem consumers read after the content: the record kind, its
+ * path, the evidence that backs it, the explanation of its rank and its confidence. A hybrid or
+ * reranked retriever wraps this one with no adapter, because the shape is the contract's.
+ */
+export const retrieveDocBridgeDocuments = (
   index: DocBridgeIndexV1,
+  query: string,
   options: DocBridgeRetrieverOptions = {},
-): DocBridgeRetriever => ({
-  retrieve: (query, req = {}) =>
-    retrieveDocBridgeChunks(index, query, { ...options, ...req }),
-})
+): RetrievedDocument[] => {
+  const limit = options.limit ?? 8
+  return searchIndex(index, query, limit, { explain: true, ...(options.agent ? { agent: true } : {}) }).map((match) => ({
+    id: match.entityId ?? match.id,
+    content: contentFor(index, match),
+    source: match.path,
+    score: match.score,
+    metadata: {
+      kind: match.kind ?? match.type,
+      type: match.type,
+      id: match.id,
+      path: match.path,
+      ...(match.evidence ? { evidence: match.evidence } : {}),
+      ...(match.explain ? { explain: match.explain } : {}),
+      ...(match.confidence ? { confidence: match.confidence } : {}),
+      ...(match.provenance ? { provenance: match.provenance } : {}),
+    },
+  }))
+}
+
+export const createDocBridgeRetriever = (index: DocBridgeIndexV1, options: DocBridgeRetrieverOptions = {}): DocBridgeRetriever => {
+  const retrieve = (request: RetrieverRequest | string, req: Pick<DocBridgeRetrieverOptions, 'limit'> = {}): RetrievedDocument[] =>
+    typeof request === 'string'
+      ? retrieveDocBridgeDocuments(index, request, { ...options, ...req })
+      : retrieveDocBridgeDocuments(index, request.query, options)
+  return { retrieve: retrieve as DocBridgeRetriever['retrieve'] }
+}
+
+/**
+ * The prose rendering of retrieved documents, as `formatRetrievedDocuments` in `@agentskit/core`
+ * renders them: a numbered block per document, its source when it has one, then its content.
+ * Mirrored for the same reason the types above are — the peer is optional and the knowledge
+ * tools must render text without it — and asserted identical to the real function by test.
+ */
+export const formatRetrievedDocuments = (documents: readonly RetrievedDocument[]): string =>
+  documents.length === 0
+    ? ''
+    : documents.map((document, position) => `[${position + 1}]\n${document.source ? `Source: ${document.source}\n` : ''}${document.content}`).join('\n\n')

package/src/rules/engine.ts

@@ -14,6 +14,16 @@ export type RuleMode = 'default' | 'recommended' | 'strict'
 
 export type RuleEngineOptions = {
   readonly config?: RulesConfig
+  /**
+   * Betweenness per entity, from `centrality` in the graph layer.
+   *
+   * Required for `centrality-risk`: without it the rule reports nothing. It used to count how
+   * many undocumented-relation findings an entity had, which measures documentation debt and
+   * calls it architecture — a module every import path runs through scored zero if it happened to
+   * be documented. Reporting nothing is better than reporting the wrong thing under a name people
+   * will act on.
+   */
+  readonly centrality?: ReadonlyMap<string, number>
   readonly preset?: RuleMode
   readonly severity?: Partial<Record<RuleId, RuleSeverity>>
   readonly ignore?: readonly RuleId[]
@@ -52,6 +62,8 @@ const diagnosticRules: Readonly<Record<string, RuleId>> = {
   STALE_DOCUMENTATION: 'stale-documentation',
   FRESHNESS_FAILURE: 'freshness',
   OWNERSHIP_GAP: 'ownership',
+  OWNERSHIP_PATH_UNOBSERVED: 'ownership',
+  IMPORT_CYCLE: 'centrality-risk',
   CENTRALITY_RISK: 'centrality-risk',
   CRITICAL_PATH_RISK: 'critical-path-risk',
 }
@@ -149,23 +161,31 @@ export const evaluateRules = (
     }
   }
 
-  const centralityThreshold = resolved.warningThresholds['centrality-risk'] ?? 3
+  /*
+   * Centrality risk: how much of the dependency structure runs through one entity.
+   *
+   * The threshold reads as a rank when it is 1 or more — "flag the three most central entities",
+   * which is what the previous count-based threshold meant to say — and as a minimum betweenness
+   * when it is below 1, for a repository that would rather set an absolute bar.
+   */
   const centralitySeverity = severityFor('centrality-risk', resolved.mode, resolved.severity)
-  if (!resolved.ignore.has('centrality-risk') && centralitySeverity !== 'off') {
-    const counts = new Map<string, number>()
-    for (const finding of findings.filter((item) => item.ruleId === 'graph-undocumented-relation')) {
-      for (const entityId of finding.entityIds ?? []) counts.set(entityId, (counts.get(entityId) ?? 0) + 1)
-    }
-    for (const [entityId, count] of [...counts.entries()].sort(([a], [b]) => a.localeCompare(b))) {
-      if (count < centralityThreshold || !criticalEntitySet.has(entityId)) continue
+  if (options.centrality?.size && !resolved.ignore.has('centrality-risk') && centralitySeverity !== 'off') {
+    const threshold = resolved.warningThresholds['centrality-risk'] ?? 3
+    const ranked = [...options.centrality.entries()]
+      .filter(([, score]) => score > 0)
+      .sort(([leftId, left], [rightId, right]) => right - left || leftId.localeCompare(rightId))
+    const flagged = threshold >= 1 ? ranked.slice(0, Math.floor(threshold)) : ranked.filter(([, score]) => score >= threshold)
+
+    for (const [entityId, score] of [...flagged].sort(([a], [b]) => a.localeCompare(b))) {
+      const related = findings.filter((item) => item.entityIds?.includes(entityId))
       findings.push({
         id: `centrality-risk:${entityId}`,
         ruleId: 'centrality-risk',
         code: 'centrality-risk',
         status: 'unresolved',
         severity: centralitySeverity,
-        message: `Critical entity has ${count} undocumented relation finding(s); static centrality is a review signal, not a runtime availability claim.`,
-        evidence: findings.filter((item) => item.ruleId === 'graph-undocumented-relation' && item.entityIds?.includes(entityId)).flatMap((item) => item.evidence),
+        message: `${entityId} carries betweenness ${score} on the import graph${criticalEntitySet.has(entityId) ? ' and is declared critical' : ''}; static centrality is a review signal, not a runtime availability claim.`,
+        evidence: related.flatMap((item) => item.evidence).slice(0, 16),
         entityIds: [entityId],
         remediation: 'Review ownership, dependency boundaries, and runtime availability before declaring an SPOF.',
       })
@@ -176,5 +196,18 @@ export const evaluateRules = (
   return { mode: resolved.mode, findings: sortedFindings, exitCode: sortedFindings.some((finding) => finding.severity === 'error') ? 1 : 0 }
 }
 
-export const parseRuleId = (value: string): RuleId => RuleIdSchema.parse(value)
-export const parseRuleSeverity = (value: string): RuleSeverity => RuleSeveritySchema.parse(value)
+export const parseRuleId = (value: string): RuleId => {
+  try {
+    return RuleIdSchema.parse(value)
+  } catch {
+    throw new Error(`Invalid enum value: ${value}`)
+  }
+}
+
+export const parseRuleSeverity = (value: string): RuleSeverity => {
+  try {
+    return RuleSeveritySchema.parse(value)
+  } catch {
+    throw new Error(`Invalid enum value: ${value}`)
+  }
+}

package/src/safety/repository.ts

@@ -3,7 +3,7 @@ import { isAbsolute, relative, resolve, sep } from 'node:path'
 
 import { minimatch } from 'minimatch'
 
-export const DEFAULT_SAFETY_EXCLUDES = ['**/.git/**', '**/node_modules/**', '**/dist/**', '**/build/**', '**/coverage/**', '**/.doc-bridge/**', '**/.turbo/**', '**/.env', '**/.env.*', '**/*secret*', '**/*credential*', '**/*.pem', '**/*.key'] as const
+export const DEFAULT_SAFETY_EXCLUDES = ['**/.git/**', '**/node_modules/**', '**/dist/**', '**/build/**', '**/coverage/**', '**/.doc-bridge/**', '**/.next/**', '**/out/**', '**/.turbo/**', '**/.svelte-kit/**', '**/.mcpb-build/**', '**/.mcpb-output/**', '**/.env', '**/.env.*', '**/*secret*', '**/*credential*', '**/*.pem', '**/*.key'] as const
 
 export type SafeWalkOptions = {
   readonly extensions?: readonly string[]