@hasna/knowledge 0.2.14 → 0.2.16

package/docs/architecture/ai-native-knowledge-base.md

@@ -217,12 +217,17 @@ filters must be applied before agent context is assembled.
 
 The first local semantic-search implementation indexes derived chunks with
 `open-knowledge embeddings index` and queries them with
+`open-knowledge search --semantic` or the lower-level
 `open-knowledge embeddings search`. It stores OpenAI embedding vectors as
-generated metadata rows, not raw source bytes, and pins each row to
-`open-files` provenance: source ref/URI, revision/hash, chunk offsets, token
-count, provider, model, dimensions, status, and timestamps. This lets the local
-SQLite index later move to pgvector or a managed hosted vector store without
-changing the CLI/MCP result contract.
+generated metadata rows, not raw source bytes, and pins each row to `open-files`
+provenance: source ref/URI, revision/hash, chunk offsets, token count, provider,
+model, dimensions, status, and timestamps. The structured `search` contract
+merges keyword FTS, wiki/index catalog hits, generated wiki chunks, and optional
+vector results. `open-knowledge search --context` and MCP `knowledge_search`
+turn those rows into reranked citation context packs with selected excerpts,
+freshness and permission notes, graph evidence, and final rerank scores. The
+local SQLite index can later move to pgvector or a managed hosted vector store
+without changing CLI/MCP result shape.
 
 ## Agent Workflow
 

package/docs/architecture/hybrid-semantic-search.md

@@ -47,13 +47,18 @@ contracts.
 The current local command surface is:
 
 ```bash
+open-knowledge search "company wiki policy" --scope project --json
+open-knowledge search "company wiki policy" --scope project --semantic --json
+open-knowledge search "company wiki policy" --scope project --context --json
 open-knowledge embeddings index --scope project --model openai:text-embedding-3-small
 open-knowledge embeddings search "company wiki policy" --scope project --json
 ```
 
-MCP exposes the same capability through `ok_embeddings_status`,
-`ok_embeddings_index`, and `ok_semantic_search`. Deterministic `--fake`
-embeddings exist for tests and offline verification only.
+`search` is the structured hybrid layer for agents. `embeddings search` is the
+lower-level vector-only command. MCP exposes the same capability through
+`ok_search`, `knowledge_search`, `ok_embeddings_status`, `ok_embeddings_index`,
+and `ok_semantic_search`. Deterministic `--fake` embeddings exist for tests and
+offline verification only.
 
 ## Hosted Indexes
 
@@ -72,16 +77,18 @@ unauthorized content.
 
 1. Normalize the query.
 2. Embed the query if a semantic-capable provider is configured.
-3. Run keyword FTS over source chunks and wiki chunks.
-4. Run vector search over source chunks and wiki pages.
-5. Expand candidate pages through backlinks and citations.
-6. Drop stale candidates whose source revision/hash no longer matches
+3. Run keyword FTS over source chunks and generated wiki chunks.
+4. Search wiki page and machine-readable index catalog rows.
+5. Run vector search over source chunks and wiki pages when semantic mode is
+   requested.
+6. Expand candidate pages through backlinks and citations.
+7. Drop stale candidates whose source revision/hash no longer matches
    `open-files`.
-7. Apply permission filters.
-8. Merge and dedupe by source revision, wiki page, citation, and text hash.
-9. Rerank by relevance, exact-match score, semantic score, freshness, citation
+8. Apply permission filters.
+9. Merge and dedupe by source revision, wiki page, citation, and text hash.
+10. Rerank by relevance, exact-match score, semantic score, freshness, citation
    quality, and wiki authority.
-10. Return structured results with source refs, citation spans, page refs,
+11. Return structured results with source refs, citation spans, page refs,
     scores, and reason codes.
 
 ## Result Shape
@@ -126,6 +133,12 @@ They should receive context packs:
 
 This keeps agent prompts stable while the retrieval internals evolve.
 
+The local context-pack implementation is available through
+`open-knowledge search --context` and MCP `knowledge_search`. It reranks merged
+search rows using exact-term coverage, citation availability, source freshness,
+and source/wiki authority, then emits excerpts and citation objects that preserve
+source refs, artifact URIs, revision/hash metadata, offsets, and provenance.
+
 ## Reindexing
 
 Reindexing is driven by source revisions:

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@hasna/knowledge",
-  "version": "0.2.14",
+  "version": "0.2.16",
   "description": "Agent-friendly local knowledge CLI with JSON output, pagination, and safe destructive actions",
   "type": "module",
   "bin": {

package/src/cli.ts

@@ -49,6 +49,8 @@ interface Flags {
   purpose?: string;
   model?: string;
   dimensions?: number;
+  semantic?: boolean;
+  context?: boolean;
   noColor?: boolean;
   scope?: string;
   olderThan?: number;
@@ -63,7 +65,7 @@ interface ParseResult {
   flags: Flags;
 }
 
-const COMMANDS = ['add', 'list', 'get', 'delete', 'update', 'archive', 'restore', 'upsert', 'untag', 'export', 'prune', 'dedupe', 'stats', 'paths', 'storage', 'db', 'wiki', 'source', 'ingest', 'reindex', 'embeddings', 'providers', 'safety', 'help'];
+const COMMANDS = ['add', 'list', 'get', 'delete', 'update', 'archive', 'restore', 'upsert', 'untag', 'export', 'prune', 'dedupe', 'stats', 'paths', 'storage', 'db', 'wiki', 'source', 'ingest', 'reindex', 'search', 'embeddings', 'providers', 'safety', 'help'];
 const COMMAND_ALIASES: Record<string, string> = {
   ls: 'list',
   rm: 'delete',
@@ -101,6 +103,8 @@ function parseArgs(argv: string[]): ParseResult {
       case '--purpose': flags.purpose = argv[i + 1]; i += 1; break;
       case '--model': flags.model = argv[i + 1]; i += 1; break;
       case '--dimensions': flags.dimensions = Number(argv[i + 1]); i += 1; break;
+      case '--semantic': flags.semantic = true; break;
+      case '--context': flags.context = true; break;
       case '--fake': flags.fake = true; break;
       case '--no-color': flags.noColor = true; break;
       case '--scope': flags.scope = argv[i + 1]; i += 1; break;
@@ -175,6 +179,7 @@ Commands:
   ingest manifest <file|s3://> Ingest an open-files manifest into knowledge.db
   ingest source <source-ref>   Ingest a read-only source ref into knowledge.db
   reindex outbox <file|s3://>  Consume open-files change events and invalidate chunks
+  search <query>               Hybrid search sources, wiki pages, indexes, or context
   embeddings status|index|search Build/query local vector embeddings
   providers status|models|check Inspect AI SDK provider config and credentials
   safety status|check|approve|audit|redact
@@ -186,6 +191,8 @@ Global Options:
   --purpose <name>            Read-only source purpose (default: knowledge_answer)
   --model <provider:model>     AI/embedding model ref
   --dimensions <n>             Embedding dimensions for local/fake providers
+  --semantic                   Include vector semantic results in search
+  --context                    Return a reranked citation context pack for search
   --fake                       Use deterministic fake embeddings for local tests
   --scope local|global|project  Store scope (default: global ~/.hasna/apps/knowledge/)
   --no-color                  Disable color output
@@ -247,6 +254,7 @@ function printCommandHelp(command: string): void {
   if (command === 'source') { console.log('Usage: open-knowledge source resolve <source-ref> [--purpose knowledge_answer|knowledge_index] [--limit <n>] [--scope local|global|project] [--json]'); return; }
   if (command === 'ingest') { console.log('Usage: open-knowledge ingest manifest <file|s3://bucket/key> | source <source-ref> [--purpose knowledge_index] [--scope local|global|project] [--json]'); return; }
   if (command === 'reindex') { console.log('Usage: open-knowledge reindex outbox <file|s3://bucket/key> [--scope local|global|project] [--json]'); return; }
+  if (command === 'search') { console.log('Usage: open-knowledge search <query> [--context] [--semantic] [--model openai:text-embedding-3-small] [--limit <n>] [--dimensions <n>] [--fake] [--scope local|global|project] [--json]'); return; }
   if (command === 'embeddings') { console.log('Usage: open-knowledge embeddings status|index|search [query] [--model openai:text-embedding-3-small] [--limit <n>] [--dimensions <n>] [--fake] [--scope local|global|project] [--json]'); return; }
   if (command === 'providers') { console.log('Usage: open-knowledge providers status|models|check [provider|model-alias] [--scope local|global|project] [--json]'); return; }
   if (command === 'safety') { console.log('Usage: open-knowledge safety status|check|approve|audit|redact [args] [--scope local|global|project] [--json]'); return; }
@@ -294,11 +302,11 @@ async function run(argv: string[]): Promise<void> {
   if (flags.completions) {
     const shell = flags.completions;
     if (shell === 'bash') {
-      console.log(`_open_knowledge() { local cur; cur="${"$"}{COMP_WORDS[COMP_CWORD]}"; COMPREPLY=($(compgen -W "add list get update archive restore upsert untag delete export prune dedupe stats paths storage db wiki source ingest reindex embeddings providers safety help ls rm edit unarchive --json --yes --help --version --desc --page --limit --search --sort --id --store --title --content --url --tag --format --completions --purpose --model --dimensions --fake --no-color --scope --archived --include-archived" -- "$cur")); }; complete -F _open_knowledge open-knowledge`);
+      console.log(`_open_knowledge() { local cur; cur="${"$"}{COMP_WORDS[COMP_CWORD]}"; COMPREPLY=($(compgen -W "add list get update archive restore upsert untag delete export prune dedupe stats paths storage db wiki source ingest reindex search embeddings providers safety help ls rm edit unarchive --json --yes --help --version --desc --page --limit --search --sort --id --store --title --content --url --tag --format --completions --purpose --model --dimensions --semantic --context --fake --no-color --scope --archived --include-archived" -- "$cur")); }; complete -F _open_knowledge open-knowledge`);
     } else if (shell === 'zsh') {
-      console.log(`#compdef open-knowledge\n_open_knowledge() { _arguments -C "1: :(add list get update archive restore upsert untag delete export prune dedupe stats paths storage db wiki source ingest reindex embeddings providers safety help ls rm edit unarchive)" "(--json)--json" "(--yes)-y" "(--help)--help" "(--version)--version" "(--desc)--desc" "(--archived)--archived" "(--include-archived)--include-archived" "(--fake)--fake" "(-p --page)"{-p,--page}"[page number]:number:" "(-l --limit)"{-l,--limit}"[items per page]:number:" "(-s --search)"{-s,--search}"[search text]:text:" "(--sort)--sort"\{created,title\}:" "(--id)--id[item id]:id:" "(--store)--store[store path]:path:" "(--title)--title[new title]:" "(--content)--content[new content]:" "(--url)--url[source url]:" "(-t --tag)"{-t,--tag}"[tag]:tag:" "(--format)--format[json|jsonl]:" "(--completions)--completions[output completions]:shell:(bash zsh fish):" "(--purpose)--purpose[purpose]:" "(--model)--model[model ref]:" "(--dimensions)--dimensions[embedding dimensions]:number:" "(--no-color)--no-color[disable color]" "(--scope)--scope"\{local,global,project\}:" }; _open_knowledge`);
+      console.log(`#compdef open-knowledge\n_open_knowledge() { _arguments -C "1: :(add list get update archive restore upsert untag delete export prune dedupe stats paths storage db wiki source ingest reindex search embeddings providers safety help ls rm edit unarchive)" "(--json)--json" "(--yes)-y" "(--help)--help" "(--version)--version" "(--desc)--desc" "(--archived)--archived" "(--include-archived)--include-archived" "(--semantic)--semantic" "(--context)--context" "(--fake)--fake" "(-p --page)"{-p,--page}"[page number]:number:" "(-l --limit)"{-l,--limit}"[items per page]:number:" "(-s --search)"{-s,--search}"[search text]:text:" "(--sort)--sort"\{created,title\}:" "(--id)--id[item id]:id:" "(--store)--store[store path]:path:" "(--title)--title[new title]:" "(--content)--content[new content]:" "(--url)--url[source url]:" "(-t --tag)"{-t,--tag}"[tag]:tag:" "(--format)--format[json|jsonl]:" "(--completions)--completions[output completions]:shell:(bash zsh fish):" "(--purpose)--purpose[purpose]:" "(--model)--model[model ref]:" "(--dimensions)--dimensions[embedding dimensions]:number:" "(--no-color)--no-color[disable color]" "(--scope)--scope"\{local,global,project\}:" }; _open_knowledge`);
     } else if (shell === 'fish') {
-      console.log(`complete -c open-knowledge -f; complete -c open-knowledge -a "add list get update archive restore upsert untag delete export prune dedupe stats paths storage db wiki source ingest reindex embeddings providers safety help ls rm edit unarchive"; complete -c open-knowledge -l json; complete -c open-knowledge -l yes -s y; complete -c open-knowledge -l help -s h; complete -c open-knowledge -l version -s v; complete -c open-knowledge -l desc; complete -c open-knowledge -l archived; complete -c open-knowledge -l include-archived; complete -c open-knowledge -l fake; complete -c open-knowledge -s p -l page; complete -c open-knowledge -s l -l limit; complete -c open-knowledge -s s -l search; complete -c open-knowledge -l sort; complete -c open-knowledge -l id; complete -c open-knowledge -l store; complete -c open-knowledge -l title; complete -c open-knowledge -l content; complete -c open-knowledge -l url; complete -c open-knowledge -s t -l tag; complete -c open-knowledge -l format; complete -c open-knowledge -l completions; complete -c open-knowledge -l purpose; complete -c open-knowledge -l model; complete -c open-knowledge -l dimensions; complete -c open-knowledge -l no-color; complete -c open-knowledge -l scope -a "local global project"`);
+      console.log(`complete -c open-knowledge -f; complete -c open-knowledge -a "add list get update archive restore upsert untag delete export prune dedupe stats paths storage db wiki source ingest reindex search embeddings providers safety help ls rm edit unarchive"; complete -c open-knowledge -l json; complete -c open-knowledge -l yes -s y; complete -c open-knowledge -l help -s h; complete -c open-knowledge -l version -s v; complete -c open-knowledge -l desc; complete -c open-knowledge -l archived; complete -c open-knowledge -l include-archived; complete -c open-knowledge -l semantic; complete -c open-knowledge -l context; complete -c open-knowledge -l fake; complete -c open-knowledge -s p -l page; complete -c open-knowledge -s l -l limit; complete -c open-knowledge -s s -l search; complete -c open-knowledge -l sort; complete -c open-knowledge -l id; complete -c open-knowledge -l store; complete -c open-knowledge -l title; complete -c open-knowledge -l content; complete -c open-knowledge -l url; complete -c open-knowledge -s t -l tag; complete -c open-knowledge -l format; complete -c open-knowledge -l completions; complete -c open-knowledge -l purpose; complete -c open-knowledge -l model; complete -c open-knowledge -l dimensions; complete -c open-knowledge -l no-color; complete -c open-knowledge -l scope -a "local global project"`);
     } else {
       throw new Error("Invalid --completions value. Use 'bash', 'zsh', or 'fish'.");
     }
@@ -578,6 +586,33 @@ async function run(argv: string[]): Promise<void> {
     throw new Error("Invalid embeddings action. Use 'status', 'index', or 'search'.");
   }
 
+  if (command === 'search') {
+    const query = positional.slice(1).join(' ');
+    if (!query) throw new Error('Usage: open-knowledge search <query>');
+    if (flags.context) {
+      const context = await service.retrieveContext({
+        query,
+        limit: flags.limit,
+        semantic: flags.semantic,
+        modelRef: flags.model,
+        dimensions: flags.dimensions,
+        fake: flags.fake,
+      });
+      output({ ok: true, ...context, message: `${context.excerpts.length} context excerpt(s)` }, flags.json);
+      return;
+    }
+    const result = await service.search({
+      query,
+      limit: flags.limit,
+      semantic: flags.semantic,
+      modelRef: flags.model,
+      dimensions: flags.dimensions,
+      fake: flags.fake,
+    });
+    output({ ok: true, ...result, message: `${result.results.length} search result(s)` }, flags.json);
+    return;
+  }
+
   if (command === 'providers') {
     const action = positional[1] ?? 'status';
     if (action === 'status') {

package/src/mcp.js

@@ -169,6 +169,40 @@ export function buildServer() {
     }
   });
 
+  registerTool(server, 'ok_search', 'Hybrid knowledge search', 'Search source chunks, generated wiki pages, sharded indexes, and optional semantic vectors', {
+    scope: scopeField,
+    query: z.string().describe('Search query'),
+    limit: z.number().optional().describe('Maximum results'),
+    semantic: z.boolean().optional().describe('Include vector semantic results'),
+    model: z.string().optional().describe('Embedding model ref, default openai:text-embedding-3-small'),
+    dimensions: z.number().optional().describe('Embedding dimensions for deterministic fake mode'),
+    fake: z.boolean().optional().describe('Use deterministic fake embeddings for local tests'),
+  }, async ({ scope, query, limit, semantic, model, dimensions, fake }) => {
+    const service = createKnowledgeService({ scope });
+    try {
+      return jsonText({ ok: true, ...await service.search({ query, limit, semantic, modelRef: model, dimensions, fake }) });
+    } catch (error) {
+      return errorText(error instanceof Error ? error.message : String(error));
+    }
+  });
+
+  registerTool(server, 'knowledge_search', 'Knowledge context search', 'Return a reranked citation context pack for agent prompts', {
+    scope: scopeField,
+    query: z.string().describe('Search query or prompt'),
+    limit: z.number().optional().describe('Maximum context results'),
+    semantic: z.boolean().optional().describe('Include vector semantic results'),
+    model: z.string().optional().describe('Embedding model ref, default openai:text-embedding-3-small'),
+    dimensions: z.number().optional().describe('Embedding dimensions for deterministic fake mode'),
+    fake: z.boolean().optional().describe('Use deterministic fake embeddings for local tests'),
+  }, async ({ scope, query, limit, semantic, model, dimensions, fake }) => {
+    const service = createKnowledgeService({ scope });
+    try {
+      return jsonText({ ok: true, ...await service.retrieveContext({ query, limit, semantic, modelRef: model, dimensions, fake }) });
+    } catch (error) {
+      return errorText(error instanceof Error ? error.message : String(error));
+    }
+  });
+
   registerTool(server, 'ok_add', 'Add a knowledge item', 'Add a new item to the knowledge store', {
     title: z.string().describe('Item title'),
     content: z.string().describe('Item content/body'),

package/src/retrieval.ts

@@ -0,0 +1,326 @@
+import { createHash } from 'node:crypto';
+import { openKnowledgeDb } from './knowledge-db';
+import { isStaleStatus } from './provenance';
+import { hybridSearch, type HybridSearchEntry, type HybridSearchOptions, type HybridSearchResult, type SearchProvenance } from './search';
+
+export interface RetrievalOptions extends HybridSearchOptions {
+  contextChars?: number;
+}
+
+export interface RerankedSearchEntry extends HybridSearchEntry {
+  rerank: {
+    base_score: number;
+    final_score: number;
+    exact_score: number;
+    citation_score: number;
+    freshness_score: number;
+    authority_score: number;
+  };
+}
+
+export interface RetrievalCitation {
+  id: string;
+  result_id: string;
+  kind: HybridSearchEntry['kind'];
+  source_uri: string | null;
+  source_ref: string | null;
+  artifact_uri: string | null;
+  artifact_path: string | null;
+  revision: string | null;
+  hash: string | null;
+  chunk_id: string | null;
+  start_offset: number | null;
+  end_offset: number | null;
+  quote: string | null;
+  provenance: SearchProvenance | null;
+}
+
+export interface RetrievalExcerpt {
+  id: string;
+  result_id: string;
+  citation_id: string | null;
+  kind: HybridSearchEntry['kind'];
+  text: string;
+  score: number;
+}
+
+export interface RetrievalGraphEvidence {
+  citations: Array<{
+    id: string;
+    chunk_id: string | null;
+    wiki_page_id: string | null;
+    source_uri: string;
+    quote: string | null;
+    start_offset: number | null;
+    end_offset: number | null;
+  }>;
+  backlinks: Array<{
+    from_page_id: string;
+    to_page_id: string;
+    label: string | null;
+  }>;
+}
+
+export interface KnowledgeContextPack {
+  query: string;
+  normalized_query: string;
+  created_at: string;
+  mode: HybridSearchResult['mode'];
+  warnings: string[];
+  search_counts: HybridSearchResult['counts'];
+  results: RerankedSearchEntry[];
+  citations: RetrievalCitation[];
+  excerpts: RetrievalExcerpt[];
+  graph: RetrievalGraphEvidence;
+  notes: {
+    permissions: string[];
+    freshness: string[];
+  };
+}
+
+interface CitationRow {
+  id: string;
+  wiki_page_id: string | null;
+  chunk_id: string | null;
+  source_uri: string;
+  quote: string | null;
+  start_offset: number | null;
+  end_offset: number | null;
+}
+
+interface BacklinkRow {
+  from_page_id: string;
+  to_page_id: string;
+  label: string | null;
+}
+
+function stableId(prefix: string, value: string): string {
+  return `${prefix}_${createHash('sha256').update(value).digest('hex').slice(0, 20)}`;
+}
+
+function normalizeQuery(query: string): string {
+  return query.normalize('NFKC').trim().replace(/\s+/g, ' ').toLowerCase();
+}
+
+function queryTerms(query: string): string[] {
+  return Array.from(new Set(normalizeQuery(query).match(/[\p{L}\p{N}_]+/gu) ?? [])).slice(0, 16);
+}
+
+function textForResult(result: HybridSearchEntry): string {
+  return [result.title, result.text].filter(Boolean).join(' ').toLowerCase();
+}
+
+function exactScore(result: HybridSearchEntry, terms: string[]): number {
+  if (terms.length === 0) return 0;
+  const text = textForResult(result);
+  const matched = terms.filter((term) => text.includes(term)).length;
+  return Number((matched / terms.length).toFixed(6));
+}
+
+function hasReadOnlyProvenance(provenance: SearchProvenance | null): boolean {
+  if (!provenance) return true;
+  if ('read_only' in provenance) return provenance.read_only === true;
+  if ('read_only_sources' in provenance) return provenance.read_only_sources === true;
+  return true;
+}
+
+function isStale(provenance: SearchProvenance | null): boolean {
+  if (!provenance) return false;
+  if ('stale' in provenance && provenance.stale) return true;
+  if ('status' in provenance) return isStaleStatus(provenance.status);
+  return false;
+}
+
+function freshnessScore(result: HybridSearchEntry): number {
+  if (isStale(result.provenance)) return 0;
+  if (result.source?.hash || result.source?.revision) return 1;
+  if (result.artifact?.hash) return 0.85;
+  if (result.provenance && 'source_refs' in result.provenance && result.provenance.source_refs.length > 0) return 0.75;
+  return 0.55;
+}
+
+function citationScore(result: HybridSearchEntry): number {
+  if (result.citation?.chunk_id && (result.source?.uri || result.artifact?.uri)) return 1;
+  if (result.provenance && 'citation_required' in result.provenance && result.provenance.citation_required) return 0.75;
+  if (result.artifact?.uri) return 0.65;
+  return 0.35;
+}
+
+function authorityScore(result: HybridSearchEntry): number {
+  if (result.kind === 'wiki_chunk') return 0.85;
+  if (result.kind === 'source_chunk') return 0.8;
+  if (result.kind === 'wiki_page') return 0.65;
+  return 0.55;
+}
+
+function rerank(result: HybridSearchEntry, terms: string[]): RerankedSearchEntry {
+  const scores = {
+    base_score: result.score,
+    exact_score: exactScore(result, terms),
+    citation_score: citationScore(result),
+    freshness_score: freshnessScore(result),
+    authority_score: authorityScore(result),
+  };
+  const final = Math.min(1,
+    scores.base_score * 0.65 +
+    scores.exact_score * 0.1 +
+    scores.citation_score * 0.1 +
+    scores.freshness_score * 0.1 +
+    scores.authority_score * 0.05,
+  );
+  const reasons = new Set(result.reasons);
+  if (scores.exact_score > 0.5) reasons.add('exact_term');
+  if (scores.citation_score >= 0.75) reasons.add('cited_source');
+  if (scores.freshness_score >= 0.85) reasons.add('fresh_source');
+  return {
+    ...result,
+    score: Number(final.toFixed(6)),
+    reasons: Array.from(reasons),
+    rerank: {
+      ...scores,
+      final_score: Number(final.toFixed(6)),
+    },
+  };
+}
+
+function quoteFor(result: HybridSearchEntry, maxChars: number): string | null {
+  const source = result.text ?? result.title;
+  if (!source) return null;
+  const normalized = source.replace(/\s+/g, ' ').trim();
+  return normalized.length <= maxChars ? normalized : `${normalized.slice(0, Math.max(0, maxChars - 1)).trim()}...`;
+}
+
+function citationFor(result: RerankedSearchEntry): RetrievalCitation {
+  const id = stableId('cite', `${result.kind}\u0000${result.id}\u0000${result.source?.uri ?? ''}\u0000${result.artifact?.uri ?? ''}`);
+  return {
+    id,
+    result_id: result.id,
+    kind: result.kind,
+    source_uri: result.source?.uri ?? null,
+    source_ref: result.source?.ref ?? null,
+    artifact_uri: result.artifact?.uri ?? null,
+    artifact_path: result.artifact?.path ?? null,
+    revision: result.source?.revision ?? null,
+    hash: result.source?.hash ?? result.artifact?.hash ?? null,
+    chunk_id: result.citation?.chunk_id ?? null,
+    start_offset: result.citation?.start_offset ?? null,
+    end_offset: result.citation?.end_offset ?? null,
+    quote: quoteFor(result, 500),
+    provenance: result.provenance,
+  };
+}
+
+function excerptFor(result: RerankedSearchEntry, citation: RetrievalCitation, contextChars: number): RetrievalExcerpt | null {
+  const text = quoteFor(result, contextChars);
+  if (!text) return null;
+  return {
+    id: stableId('excerpt', `${result.kind}\u0000${result.id}`),
+    result_id: result.id,
+    citation_id: citation.id,
+    kind: result.kind,
+    text,
+    score: result.score,
+  };
+}
+
+function placeholders(values: unknown[]): string {
+  return values.map(() => '?').join(', ');
+}
+
+function loadGraphEvidence(dbPath: string, results: RerankedSearchEntry[]): RetrievalGraphEvidence {
+  const chunkIds = results.map((result) => result.citation?.chunk_id).filter((id): id is string => Boolean(id));
+  const wikiPageIds = results.filter((result) => result.kind === 'wiki_page').map((result) => result.id);
+  const citations: CitationRow[] = [];
+  const backlinks: BacklinkRow[] = [];
+  if (chunkIds.length === 0 && wikiPageIds.length === 0) return { citations, backlinks };
+
+  const db = openKnowledgeDb(dbPath);
+  try {
+    if (chunkIds.length > 0) {
+      citations.push(...db.query<CitationRow, string[]>(
+        `SELECT id, wiki_page_id, chunk_id, source_uri, quote, start_offset, end_offset
+         FROM citations
+         WHERE chunk_id IN (${placeholders(chunkIds)})
+         ORDER BY created_at DESC
+         LIMIT 50`,
+      ).all(...chunkIds));
+    }
+    if (wikiPageIds.length > 0) {
+      citations.push(...db.query<CitationRow, string[]>(
+        `SELECT id, wiki_page_id, chunk_id, source_uri, quote, start_offset, end_offset
+         FROM citations
+         WHERE wiki_page_id IN (${placeholders(wikiPageIds)})
+         ORDER BY created_at DESC
+         LIMIT 50`,
+      ).all(...wikiPageIds));
+      backlinks.push(...db.query<BacklinkRow, string[]>(
+        `SELECT from_page_id, to_page_id, label
+         FROM wiki_backlinks
+         WHERE from_page_id IN (${placeholders(wikiPageIds)}) OR to_page_id IN (${placeholders(wikiPageIds)})
+         LIMIT 50`,
+      ).all(...wikiPageIds, ...wikiPageIds));
+    }
+  } finally {
+    db.close();
+  }
+  return { citations, backlinks };
+}
+
+export async function retrieveKnowledgeContext(options: RetrievalOptions): Promise<KnowledgeContextPack> {
+  const contextChars = Math.max(200, Math.min(options.contextChars ?? 1200, 4000));
+  const search = await hybridSearch(options);
+  const terms = queryTerms(search.query);
+  const warnings = [...search.warnings];
+  const permissionNotes = new Set<string>();
+  const freshnessNotes = new Set<string>();
+
+  const filtered = search.results.filter((result) => {
+    if (!hasReadOnlyProvenance(result.provenance)) {
+      warnings.push(`permission_filtered: ${result.kind}:${result.id}`);
+      permissionNotes.add('Dropped a result because provenance was not read-only.');
+      return false;
+    }
+    if (isStale(result.provenance)) {
+      warnings.push(`stale_filtered: ${result.kind}:${result.id}`);
+      freshnessNotes.add('Dropped a stale result whose source status requires reindexing.');
+      return false;
+    }
+    return true;
+  });
+
+  const results = filtered
+    .map((result) => rerank(result, terms))
+    .sort((a, b) => b.score - a.score || a.id.localeCompare(b.id))
+    .slice(0, search.limit);
+
+  const citations = results.map(citationFor);
+  const excerpts = results
+    .map((result, index) => excerptFor(result, citations[index], contextChars))
+    .filter((entry): entry is RetrievalExcerpt => Boolean(entry));
+
+  for (const result of results) {
+    if (result.provenance && 'read_only' in result.provenance && result.provenance.read_only) {
+      permissionNotes.add('All source-backed excerpts are read-only and citation-required.');
+    }
+    if (result.rerank.freshness_score >= 0.85) {
+      freshnessNotes.add('Fresh source revision/hash or artifact hash is present for top context.');
+    }
+  }
+
+  return {
+    query: search.query,
+    normalized_query: normalizeQuery(search.query),
+    created_at: new Date().toISOString(),
+    mode: search.mode,
+    warnings,
+    search_counts: search.counts,
+    results,
+    citations,
+    excerpts,
+    graph: loadGraphEvidence(options.dbPath, results),
+    notes: {
+      permissions: Array.from(permissionNotes),
+      freshness: Array.from(freshnessNotes),
+    },
+  };
+}