@hasna/knowledge 0.2.18 → 0.2.20

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

@@ -229,6 +229,13 @@ 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.
 
+Index freshness is explicit. `reindex_queue` tracks missing or stale embedding
+work, `open-knowledge reindex status|enqueue|embeddings` operates the local
+queue, and MCP exposes the same controls through `ok_reindex_status`,
+`ok_reindex_enqueue`, and `ok_reindex_embeddings`. Hosted mode can map the same
+contract to worker queues, S3/object artifact sync, Postgres/pgvector, or a
+managed vector index while preserving the local command shape.
+
 ## Agent Workflow
 
 The target user flow is:

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

@@ -35,6 +35,8 @@ Local mode starts with SQLite:
 - `vector_index_entries` stores searchable embedding rows with provider/model,
   dimensions, source revision/hash, chunk offsets, status, timestamps, and
   provenance metadata.
+- `reindex_queue` stores idempotent refresh jobs for missing/stale embedding
+  work.
 - `wiki_pages`, `wiki_backlinks`, and `citations` provide graph and provenance
   signals.
 - `knowledge_indexes` tracks generated machine-readable shards.
@@ -50,6 +52,8 @@ The current local command surface is:
 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 reindex status --scope project --json
+open-knowledge reindex embeddings --scope project --fake --json
 open-knowledge embeddings index --scope project --model openai:text-embedding-3-small
 open-knowledge embeddings search "company wiki policy" --scope project --json
 ```
@@ -57,7 +61,8 @@ open-knowledge embeddings search "company wiki policy" --scope project --json
 `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
+`ok_semantic_search`, `ok_reindex_status`, `ok_reindex_enqueue`, and
+`ok_reindex_embeddings`. Deterministic `--fake` embeddings exist for tests and
 offline verification only.
 
 ## Hosted Indexes
@@ -158,6 +163,10 @@ Reindexing is driven by source revisions:
 - Local outbox consumption deletes stale `chunk_embeddings` and
   `vector_index_entries` for deleted revisions, so semantic search cannot return
   removed source chunks.
+- `reindex status` reports missing embeddings, stale revisions, queued work, and
+  vector counts; `reindex enqueue` records missing work in `reindex_queue`.
+- `reindex embeddings` performs incremental refreshes, while `--full` clears and
+  rebuilds `chunk_embeddings` and `vector_index_entries`.
 - Wiki pages should track the source revisions they cite so lint can flag stale
   pages.
 - Embedding refresh jobs should be idempotent and checkpointed in `runs` and
@@ -171,3 +180,12 @@ Reindexing is driven by source revisions:
 - Permission filters run before model context assembly.
 - Retrieval internals can swap from JSON vectors to pgvector or managed vector
   stores without changing CLI/MCP result contracts.
+
+## Evaluation Fixtures
+
+`tests/semantic-evals.test.ts` and `tests/fixtures/semantic-eval-fixtures.ts`
+seed no-network corpora for retrieval quality checks. The fixtures cover
+keyword hits, deterministic fake-vector fallback for synonym-style prompts,
+citation correctness, stale revision filtering, non-read-only provenance
+filtering, rerank ordering, generated wiki-page retrieval, missing-source
+answers, and `knowledge <prompt>` context assembly.

package/package.json

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

package/src/cli.ts

@@ -57,6 +57,7 @@ interface Flags {
   provider?: string;
   domain?: string[];
   fileResults?: boolean;
+  full?: boolean;
   noColor?: boolean;
   scope?: string;
   olderThan?: number;
@@ -117,6 +118,7 @@ function parseArgs(argv: string[]): ParseResult {
       case '--provider': flags.provider = argv[i + 1]; i += 1; break;
       case '--domain': flags.domain = [...(flags.domain ?? []), argv[i + 1]]; i += 1; break;
       case '--file-results': flags.fileResults = true; break;
+      case '--full': flags.full = 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;
@@ -194,7 +196,7 @@ Commands:
   source resolve <source-ref>  Resolve read-only source content and citation evidence
   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
+  reindex status|enqueue|embeddings|outbox Inspect/refresh search indexes
   search <query>               Hybrid search sources, wiki pages, indexes, or context
   web search <query>           Provider-native web search with citations
   ask|build <prompt>           Build a read-only citation answer/context pack
@@ -216,6 +218,7 @@ Global Options:
   --provider <name>            Provider override for web search
   --domain <domain>            Restrict provider web search to a domain
   --file-results               File web snippets as web source refs
+  --full                       Force full embedding index rebuild
   --fake                       Use deterministic fake embeddings for local tests
   --scope local|global|project  Store scope (default: global ~/.hasna/apps/knowledge/)
   --no-color                  Disable color output
@@ -276,7 +279,7 @@ function printCommandHelp(command: string): void {
   if (command === 'wiki') { console.log('Usage: open-knowledge wiki init [--scope local|global|project] [--json]'); return; }
   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 === 'reindex') { console.log('Usage: open-knowledge reindex status|enqueue|embeddings|outbox [file|s3://bucket/key] [--full] [--fake] [--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 === 'web') { console.log('Usage: open-knowledge web search <query> [--provider openai|anthropic] [--model provider:model] [--domain <domain>] [--file-results] [--fake] [--scope local|global|project] [--json]'); return; }
   if (command === 'ask' || command === 'build' || command === 'knowledge') { console.log('Usage: open-knowledge ask|build <prompt> [--generate] [--semantic] [--model default|provider:model] [--approve-write] [--scope local|global|project] [--json]'); return; }
@@ -327,11 +330,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 search web ask build embeddings providers safety help ls rm edit unarchive knowledge --json --yes --help --version --desc --page --limit --search --sort --id --store --title --content --url --tag --format --completions --purpose --model --dimensions --semantic --context --generate --approve-write --provider --domain --file-results --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 web ask build embeddings providers safety help ls rm edit unarchive knowledge --json --yes --help --version --desc --page --limit --search --sort --id --store --title --content --url --tag --format --completions --purpose --model --dimensions --semantic --context --generate --approve-write --provider --domain --file-results --full --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 search web ask build embeddings providers safety help ls rm edit unarchive knowledge)" "(--json)--json" "(--yes)-y" "(--help)--help" "(--version)--version" "(--desc)--desc" "(--archived)--archived" "(--include-archived)--include-archived" "(--semantic)--semantic" "(--context)--context" "(--generate)--generate" "(--approve-write)--approve-write" "(--file-results)--file-results" "(--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:" "(--provider)--provider[provider]:" "(--domain)--domain[domain]:" "(--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 web ask build embeddings providers safety help ls rm edit unarchive knowledge)" "(--json)--json" "(--yes)-y" "(--help)--help" "(--version)--version" "(--desc)--desc" "(--archived)--archived" "(--include-archived)--include-archived" "(--semantic)--semantic" "(--context)--context" "(--generate)--generate" "(--approve-write)--approve-write" "(--file-results)--file-results" "(--full)--full" "(--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:" "(--provider)--provider[provider]:" "(--domain)--domain[domain]:" "(--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 search web ask build embeddings providers safety help ls rm edit unarchive knowledge"; 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 generate; complete -c open-knowledge -l approve-write; complete -c open-knowledge -l provider; complete -c open-knowledge -l domain; complete -c open-knowledge -l file-results; 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 web ask build embeddings providers safety help ls rm edit unarchive knowledge"; 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 generate; complete -c open-knowledge -l approve-write; complete -c open-knowledge -l provider; complete -c open-knowledge -l domain; complete -c open-knowledge -l file-results; complete -c open-knowledge -l full; 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'.");
     }
@@ -574,13 +577,44 @@ async function run(argv: string[]): Promise<void> {
   }
 
   if (command === 'reindex') {
-    const action = positional[1] ?? '';
-    if (action !== 'outbox') throw new Error("Invalid reindex action. Use 'outbox'.");
-    const input = positional[2];
-    if (!input) throw new Error('Usage: open-knowledge reindex outbox <file|s3://bucket/key>');
-    const result = await service.consumeOutbox(input);
-    output({ ok: true, ...result, message: `Consumed ${result.events_seen} outbox event(s)` }, flags.json);
-    return;
+    const action = positional[1] ?? 'status';
+    if (action === 'status') {
+      const result = service.reindexHealth({
+        modelRef: flags.model,
+        dimensions: flags.dimensions,
+        fake: flags.fake,
+      });
+      output({ ok: true, ...result, message: `${result.missing_embeddings} chunk(s) missing embeddings` }, flags.json);
+      return;
+    }
+    if (action === 'enqueue') {
+      const result = service.enqueueReindex({
+        modelRef: flags.model,
+        dimensions: flags.dimensions,
+        fake: flags.fake,
+      });
+      output({ ok: true, ...result, message: `Queued ${result.enqueued} embedding refresh item(s)` }, flags.json);
+      return;
+    }
+    if (action === 'embeddings') {
+      const result = await service.refreshEmbeddings({
+        full: flags.full,
+        limit: flags.limit,
+        modelRef: flags.model,
+        dimensions: flags.dimensions,
+        fake: flags.fake,
+      });
+      output({ ok: true, ...result, message: `Embedded ${result.indexed.chunks_embedded} chunk(s)` }, flags.json);
+      return;
+    }
+    if (action === 'outbox') {
+      const input = positional[2];
+      if (!input) throw new Error('Usage: open-knowledge reindex outbox <file|s3://bucket/key>');
+      const result = await service.consumeOutbox(input);
+      output({ ok: true, ...result, message: `Consumed ${result.events_seen} outbox event(s)` }, flags.json);
+      return;
+    }
+    throw new Error("Invalid reindex action. Use 'status', 'enqueue', 'embeddings', or 'outbox'.");
   }
 
   if (command === 'embeddings') {

package/src/knowledge-db.ts

@@ -1,7 +1,7 @@
 import { Database } from 'bun:sqlite';
 import { ensureParentDir } from './workspace';
 
-export const CURRENT_SCHEMA_VERSION = 4;
+export const CURRENT_SCHEMA_VERSION = 5;
 
 export interface KnowledgeDbStats {
   schema_version: number;
@@ -19,6 +19,7 @@ export interface KnowledgeDbStats {
   storage_objects: number;
   embeddings: number;
   vector_entries: number;
+  reindex_queue: number;
 }
 
 const MIGRATION_1 = `
@@ -271,6 +272,29 @@ INSERT OR IGNORE INTO schema_versions(version, applied_at)
 VALUES (4, datetime('now'));
 `;
 
+const MIGRATION_5 = `
+CREATE TABLE IF NOT EXISTS reindex_queue (
+  id TEXT PRIMARY KEY,
+  kind TEXT NOT NULL,
+  target_id TEXT NOT NULL,
+  source_uri TEXT,
+  reason TEXT NOT NULL,
+  status TEXT NOT NULL DEFAULT 'pending',
+  attempts INTEGER NOT NULL DEFAULT 0,
+  metadata_json TEXT NOT NULL DEFAULT '{}',
+  created_at TEXT NOT NULL,
+  updated_at TEXT NOT NULL,
+  UNIQUE(kind, target_id, reason)
+);
+
+CREATE INDEX IF NOT EXISTS idx_reindex_queue_status ON reindex_queue(status);
+CREATE INDEX IF NOT EXISTS idx_reindex_queue_kind_target ON reindex_queue(kind, target_id);
+CREATE INDEX IF NOT EXISTS idx_reindex_queue_source_uri ON reindex_queue(source_uri);
+
+INSERT OR IGNORE INTO schema_versions(version, applied_at)
+VALUES (5, datetime('now'));
+`;
+
 export function openKnowledgeDb(path: string): Database {
   ensureParentDir(path);
   const db = new Database(path);
@@ -286,6 +310,7 @@ export function migrateKnowledgeDb(path: string): { path: string; schema_version
     if (getSchemaVersion(db) < 2) db.exec(MIGRATION_2);
     if (getSchemaVersion(db) < 3) db.exec(MIGRATION_3);
     if (getSchemaVersion(db) < 4) db.exec(MIGRATION_4);
+    if (getSchemaVersion(db) < 5) db.exec(MIGRATION_5);
     return { path, schema_version: getSchemaVersion(db) };
   } finally {
     db.close();
@@ -321,6 +346,7 @@ export function getKnowledgeDbStats(path: string): KnowledgeDbStats {
       storage_objects: count(db, 'storage_objects'),
       embeddings: count(db, 'chunk_embeddings'),
       vector_entries: count(db, 'vector_index_entries'),
+      reindex_queue: count(db, 'reindex_queue'),
     };
   } finally {
     db.close();

package/src/mcp.js

@@ -153,6 +153,50 @@ export function buildServer() {
     }
   });
 
+  registerTool(server, 'ok_reindex_status', 'Reindex status', 'Inspect missing embeddings, queued jobs, stale revisions, and vector index health', {
+    scope: scopeField,
+    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, model, dimensions, fake }) => {
+    const service = createKnowledgeService({ scope });
+    try {
+      return jsonText({ ok: true, ...service.reindexHealth({ modelRef: model, dimensions, fake }) });
+    } catch (error) {
+      return errorText(error instanceof Error ? error.message : String(error));
+    }
+  });
+
+  registerTool(server, 'ok_reindex_enqueue', 'Enqueue reindex work', 'Queue missing embedding refresh jobs for indexed source chunks', {
+    scope: scopeField,
+    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, model, dimensions, fake }) => {
+    const service = createKnowledgeService({ scope });
+    try {
+      return jsonText({ ok: true, ...service.enqueueReindex({ modelRef: model, dimensions, fake }) });
+    } catch (error) {
+      return errorText(error instanceof Error ? error.message : String(error));
+    }
+  });
+
+  registerTool(server, 'ok_reindex_embeddings', 'Refresh embedding index', 'Run incremental or full embedding refresh jobs with run-ledger tracking', {
+    scope: scopeField,
+    full: z.boolean().optional().describe('Delete and rebuild all embedding/vector rows first'),
+    limit: z.number().optional().describe('Maximum chunks to embed'),
+    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, full, limit, model, dimensions, fake }) => {
+    const service = createKnowledgeService({ scope });
+    try {
+      return jsonText({ ok: true, ...await service.refreshEmbeddings({ full, limit, modelRef: model, dimensions, fake }) });
+    } catch (error) {
+      return errorText(error instanceof Error ? error.message : String(error));
+    }
+  });
+
   registerTool(server, 'ok_semantic_search', 'Semantic search', 'Search the local vector index and return cited chunks with provenance', {
     scope: scopeField,
     query: z.string().describe('Semantic query'),

package/src/reindex.ts

@@ -0,0 +1,260 @@
+import { createHash, randomUUID } from 'node:crypto';
+import { indexKnowledgeEmbeddings, resolveEmbeddingModelRef, type EmbeddingRuntimeOptions } from './embeddings';
+import { migrateKnowledgeDb, openKnowledgeDb } from './knowledge-db';
+import { parseModelRef } from './providers';
+import type { KnowledgeConfig } from './workspace';
+
+export interface ReindexRuntimeOptions extends EmbeddingRuntimeOptions {
+  dbPath: string;
+  config?: KnowledgeConfig;
+  now?: Date;
+}
+
+export interface ReindexHealthResult {
+  schema_version: number;
+  chunks: number;
+  vector_entries: number;
+  missing_embeddings: number;
+  queued: Record<string, number>;
+  stale_revisions: number;
+}
+
+export interface ReindexEnqueueResult {
+  enqueued: number;
+  already_queued: number;
+  reason: string;
+}
+
+export interface ReindexEmbeddingsResult {
+  run_id: string;
+  full: boolean;
+  deleted_embeddings: number;
+  deleted_vector_entries: number;
+  queued: ReindexEnqueueResult;
+  indexed: Awaited<ReturnType<typeof indexKnowledgeEmbeddings>>;
+  completed_queue_items: number;
+}
+
+interface MissingChunkRow {
+  chunk_id: string;
+  source_revision_id: string | null;
+  source_uri: string | null;
+}
+
+function stableId(prefix: string, value: string): string {
+  return `${prefix}_${createHash('sha256').update(value).digest('hex').slice(0, 20)}`;
+}
+
+function queueCounts(dbPath: string): Record<string, number> {
+  const db = openKnowledgeDb(dbPath);
+  try {
+    const rows = db.query<{ status: string; n: number }, []>(
+      `SELECT status, COUNT(*) AS n FROM reindex_queue GROUP BY status ORDER BY status`,
+    ).all();
+    return Object.fromEntries(rows.map((row) => [row.status, row.n]));
+  } finally {
+    db.close();
+  }
+}
+
+function missingEmbeddingRows(dbPath: string, options: ReindexRuntimeOptions): MissingChunkRow[] {
+  const modelRef = resolveEmbeddingModelRef(options.modelRef, options.config);
+  const parsed = parseModelRef(modelRef);
+  const db = openKnowledgeDb(dbPath);
+  try {
+    return db.query<MissingChunkRow, [string, string]>(
+      `SELECT c.id AS chunk_id, c.source_revision_id, s.uri AS source_uri
+       FROM chunks c
+       LEFT JOIN source_revisions sr ON sr.id = c.source_revision_id
+       LEFT JOIN sources s ON s.id = sr.source_id
+       LEFT JOIN vector_index_entries v ON v.chunk_id = c.id AND v.provider = ? AND v.model = ?
+       WHERE v.id IS NULL
+       ORDER BY c.created_at ASC, c.ordinal ASC`,
+    ).all(parsed.provider, parsed.model);
+  } finally {
+    db.close();
+  }
+}
+
+export function reindexHealth(options: ReindexRuntimeOptions): ReindexHealthResult {
+  migrateKnowledgeDb(options.dbPath);
+  const db = openKnowledgeDb(options.dbPath);
+  try {
+    const version = db.query<{ version: number }, []>('SELECT MAX(version) AS version FROM schema_versions').get()?.version ?? 0;
+    const chunks = db.query<{ n: number }, []>('SELECT COUNT(*) AS n FROM chunks').get()?.n ?? 0;
+    const vectorEntries = db.query<{ n: number }, []>('SELECT COUNT(*) AS n FROM vector_index_entries').get()?.n ?? 0;
+    const missing = missingEmbeddingRows(options.dbPath, options).length;
+    const stale = db.query<{ n: number }, []>(
+      `SELECT COUNT(*) AS n FROM source_revisions
+       WHERE metadata_json LIKE '%"reindex_required":true%' OR metadata_json LIKE '%"status":"stale"%'`,
+    ).get()?.n ?? 0;
+    return {
+      schema_version: version,
+      chunks,
+      vector_entries: vectorEntries,
+      missing_embeddings: missing,
+      queued: queueCounts(options.dbPath),
+      stale_revisions: stale,
+    };
+  } finally {
+    db.close();
+  }
+}
+
+export function enqueueMissingEmbeddings(options: ReindexRuntimeOptions & { reason?: string }): ReindexEnqueueResult {
+  migrateKnowledgeDb(options.dbPath);
+  const now = (options.now ?? new Date()).toISOString();
+  const reason = options.reason ?? 'missing_embedding';
+  const rows = missingEmbeddingRows(options.dbPath, options);
+  const db = openKnowledgeDb(options.dbPath);
+  let enqueued = 0;
+  let alreadyQueued = 0;
+  try {
+    const write = db.transaction(() => {
+      for (const row of rows) {
+        const id = stableId('rq', `embedding\u0000${row.chunk_id}\u0000${reason}`);
+        const before = db.query<{ id: string }, [string, string, string]>(
+          'SELECT id FROM reindex_queue WHERE kind = ? AND target_id = ? AND reason = ?',
+        ).get('embedding', row.chunk_id, reason);
+        if (before) {
+          alreadyQueued += 1;
+          continue;
+        }
+        db.run(
+          `INSERT INTO reindex_queue (id, kind, target_id, source_uri, reason, status, metadata_json, created_at, updated_at)
+           VALUES (?, ?, ?, ?, ?, ?, ?, ?, ?)`,
+          [
+            id,
+            'embedding',
+            row.chunk_id,
+            row.source_uri,
+            reason,
+            'pending',
+            JSON.stringify({ source_revision_id: row.source_revision_id }),
+            now,
+            now,
+          ],
+        );
+        enqueued += 1;
+      }
+    });
+    write();
+  } finally {
+    db.close();
+  }
+  return { enqueued, already_queued: alreadyQueued, reason };
+}
+
+function clearEmbeddingIndex(dbPath: string): { embeddings: number; vectorEntries: number } {
+  const db = openKnowledgeDb(dbPath);
+  try {
+    const embeddings = db.query<{ n: number }, []>('SELECT COUNT(*) AS n FROM chunk_embeddings').get()?.n ?? 0;
+    const vectorEntries = db.query<{ n: number }, []>('SELECT COUNT(*) AS n FROM vector_index_entries').get()?.n ?? 0;
+    db.run('DELETE FROM vector_index_entries');
+    db.run('DELETE FROM chunk_embeddings');
+    return { embeddings, vectorEntries };
+  } finally {
+    db.close();
+  }
+}
+
+function completeIndexedQueueItems(dbPath: string, options: ReindexRuntimeOptions, now: string): number {
+  const modelRef = resolveEmbeddingModelRef(options.modelRef, options.config);
+  const parsed = parseModelRef(modelRef);
+  const db = openKnowledgeDb(dbPath);
+  try {
+    const result = db.run(
+      `UPDATE reindex_queue
+       SET status = ?, updated_at = ?
+       WHERE kind = ?
+         AND status = ?
+         AND EXISTS (
+           SELECT 1 FROM vector_index_entries v
+           WHERE v.chunk_id = reindex_queue.target_id
+             AND v.provider = ?
+             AND v.model = ?
+         )`,
+      ['completed', now, 'embedding', 'pending', parsed.provider, parsed.model],
+    );
+    return result.changes;
+  } finally {
+    db.close();
+  }
+}
+
+export async function refreshEmbeddingIndex(options: ReindexRuntimeOptions & { full?: boolean; limit?: number }): Promise<ReindexEmbeddingsResult> {
+  migrateKnowledgeDb(options.dbPath);
+  const now = (options.now ?? new Date()).toISOString();
+  const runId = `run_${randomUUID()}`;
+  const deleted = options.full ? clearEmbeddingIndex(options.dbPath) : { embeddings: 0, vectorEntries: 0 };
+  const queued = enqueueMissingEmbeddings({ ...options, reason: options.full ? 'full_embedding_rebuild' : 'missing_embedding' });
+  const db = openKnowledgeDb(options.dbPath);
+  try {
+    db.run(
+      `INSERT INTO runs (id, type, prompt, status, provider, model, metadata_json, created_at, updated_at)
+       VALUES (?, ?, ?, ?, ?, ?, ?, ?, ?)`,
+      [
+        runId,
+        'embedding-refresh',
+        options.full ? 'full' : 'incremental',
+        'running',
+        'local',
+        resolveEmbeddingModelRef(options.modelRef, options.config),
+        JSON.stringify({ full: options.full === true, queued }),
+        now,
+        now,
+      ],
+    );
+  } finally {
+    db.close();
+  }
+
+  const indexed = await indexKnowledgeEmbeddings({
+    dbPath: options.dbPath,
+    config: options.config,
+    env: options.env,
+    modelRef: options.modelRef,
+    dimensions: options.dimensions,
+    fake: options.fake,
+    limit: options.limit,
+    now: options.now,
+  });
+
+  const completedQueueItems = completeIndexedQueueItems(options.dbPath, options, now);
+  const doneDb = openKnowledgeDb(options.dbPath);
+  try {
+    doneDb.run(
+      `UPDATE runs SET status = ?, metadata_json = ?, updated_at = ? WHERE id = ?`,
+      [
+        'completed',
+        JSON.stringify({ full: options.full === true, queued, indexed, completed_queue_items: completedQueueItems }),
+        now,
+        runId,
+      ],
+    );
+    doneDb.run(
+      `INSERT INTO run_events (id, run_id, level, event, metadata_json, created_at)
+       VALUES (?, ?, ?, ?, ?, ?)`,
+      [
+        `evt_${randomUUID()}`,
+        runId,
+        'info',
+        'embedding_refresh_completed',
+        JSON.stringify({ queued, indexed, completed_queue_items: completedQueueItems }),
+        now,
+      ],
+    );
+  } finally {
+    doneDb.close();
+  }
+
+  return {
+    run_id: runId,
+    full: options.full === true,
+    deleted_embeddings: deleted.embeddings,
+    deleted_vector_entries: deleted.vectorEntries,
+    queued,
+    indexed,
+    completed_queue_items: completedQueueItems,
+  };
+}

package/src/service.ts

@@ -13,6 +13,7 @@ import { ingestOpenFilesManifest } from './manifest-ingest';
 import { ingestSourceRef } from './source-ingest';
 import { resolveOpenFilesSource } from './source-resolver';
 import { providerStatus, listModelRegistry, type ProviderStatusResult, type ModelRegistryEntry } from './providers';
+import { enqueueMissingEmbeddings, refreshEmbeddingIndex, reindexHealth, type ReindexRuntimeOptions } from './reindex';
 import { retrieveKnowledgeContext, type RetrievalOptions } from './retrieval';
 import { hybridSearch, type HybridSearchOptions } from './search';
 import { resolveSafetyPolicy } from './safety';
@@ -188,6 +189,33 @@ export class KnowledgeService {
     });
   }
 
+  reindexHealth(options: Omit<ReindexRuntimeOptions, 'dbPath' | 'config'> = {}) {
+    const workspace = this.ensureWorkspace();
+    return reindexHealth({
+      ...options,
+      dbPath: workspace.knowledgeDbPath,
+      config: this.config(),
+    });
+  }
+
+  enqueueReindex(options: Omit<ReindexRuntimeOptions, 'dbPath' | 'config'> = {}) {
+    const workspace = this.ensureWorkspace();
+    return enqueueMissingEmbeddings({
+      ...options,
+      dbPath: workspace.knowledgeDbPath,
+      config: this.config(),
+    });
+  }
+
+  async refreshEmbeddings(options: Omit<ReindexRuntimeOptions & { full?: boolean; limit?: number }, 'dbPath' | 'config'> = {}) {
+    const workspace = this.ensureWorkspace();
+    return refreshEmbeddingIndex({
+      ...options,
+      dbPath: workspace.knowledgeDbPath,
+      config: this.config(),
+    });
+  }
+
   providerStatus(env: Record<string, string | undefined> = process.env): ProviderStatusResult {
     return providerStatus(this.config(), env);
   }