@wei840222/qmd 2026.9.6 → 2026.9.27

package/dist/store.d.ts

@@ -18,6 +18,8 @@ import type { LLM } from "./llm.js";
 import { LlamaCpp, formatQueryForEmbedding, formatDocForEmbedding, type ILLMSession } from "./llm.js";
 import type { NamedCollection, Collection, CollectionConfig } from "./collections.js";
 import type { IndexDiagnostics } from "./diagnostics.js";
+import { type DocumentMetadata } from "./metadata.js";
+import { type MetadataFilter } from "./metadata-filter.js";
 export declare const DEFAULT_EMBED_MODEL = "hf:ggml-org/embeddinggemma-300M-GGUF/embeddinggemma-300M-Q8_0.gguf";
 export declare const DEFAULT_RERANK_MODEL = "hf:ggml-org/Qwen3-Reranker-0.6B-Q8_0-GGUF/qwen3-reranker-0.6b-q8_0.gguf";
 export declare const DEFAULT_QUERY_MODEL = "hf:tobil/qmd-query-expansion-1.7B-gguf/qmd-query-expansion-1.7B-q4_k_m.gguf";
@@ -310,15 +312,16 @@ export type Store = {
     isVirtualPath: typeof isVirtualPath;
     resolveVirtualPath: (virtualPath: string) => string | null;
     toVirtualPath: (absolutePath: string) => string | null;
-    searchCharFTS: (query: string, limit?: number, collectionFilter?: CollectionFilter) => SearchResult[];
-    searchFTS: (query: string, limit?: number, collectionFilter?: CollectionFilter) => SearchResult[];
-    searchVec: (query: string, model: string, limit?: number, collectionFilter?: CollectionFilter, session?: ILLMSession, precomputedEmbedding?: number[]) => Promise<SearchResult[]>;
+    searchCharFTS: (query: string, limit?: number, collectionFilter?: CollectionFilter, filter?: MetadataFilter) => SearchResult[];
+    searchFTS: (query: string, limit?: number, collectionFilter?: CollectionFilter, filter?: MetadataFilter) => SearchResult[];
+    searchVec: (query: string, model: string, limit?: number, collectionFilter?: CollectionFilter, session?: ILLMSession, precomputedEmbedding?: number[], filter?: MetadataFilter) => Promise<SearchResult[]>;
     expandQuery: (query: string, model?: string, expansionContext?: string, options?: QueryExpansionOptions) => Promise<ExpandedQuery[]>;
     /** Drop the cached expansion for a query so the next call regenerates. */
     invalidateExpansionCache: (query: string, expansionContext?: string, options?: QueryExpansionOptions) => void;
     rerank: (query: string, documents: {
         file: string;
         text: string;
+        title?: string;
     }[], model?: string, rerankContext?: string) => Promise<{
         file: string;
         score: number;
@@ -347,7 +350,7 @@ export type Store = {
         hash: string;
     } | null;
     insertContent: (hash: string, content: string, createdAt: string) => void;
-    insertDocument: (collectionName: string, path: string, title: string, hash: string, createdAt: string, modifiedAt: string) => void;
+    insertDocument: (collectionName: string, path: string, title: string, hash: string, createdAt: string, modifiedAt: string) => number;
     findActiveDocument: (collectionName: string, path: string) => {
         id: number;
         hash: string;
@@ -367,6 +370,7 @@ export type Store = {
         body: string;
         path: string;
     }[];
+    insertEmbedding: (hash: string, seq: number, pos: number, embedding: Float32Array, model: string, embeddedAt: string, totalChunks?: number, fingerprint?: string, lease?: EmbeddingBuildLease) => void;
 };
 export type ReindexProgress = {
     file: string;
@@ -385,6 +389,12 @@ export type ReindexResult = {
     orphanedCleaned: number;
     skipped: number;
     skippedFiles: ReindexSkippedFile[];
+    /** Documents whose qmd.metadata frontmatter failed extraction this pass. */
+    metadataErrors: number;
+    metadataErrorFiles?: {
+        file: string;
+        error: string;
+    }[];
 };
 /**
  * Re-index a single collection by scanning the filesystem and updating the database.
@@ -501,6 +511,7 @@ export declare function handelize(path: string): string;
  * Search result extends DocumentResult with score and source info
  */
 export type SearchResult = DocumentResult & {
+    metadata: DocumentMetadata;
     score: number;
     source: "fts" | "vec";
     chunkPos?: number;
@@ -612,6 +623,8 @@ export type IndexStatus = {
     totalDocuments: number;
     needsEmbedding: number;
     hasVectorIndex: boolean;
+    /** Active documents without current, error-free metadata extraction. */
+    pendingMetadata: number;
     collections: CollectionInfo[];
     /** Additive diagnostics populated by high-level composition roots. */
     diagnostics?: IndexDiagnostics;
@@ -707,10 +720,11 @@ export declare function extractTitle(content: string, filename: string): string;
 export declare function insertContent(db: Database, hash: string, content: string, createdAt: string): void;
 /**
  * Insert a new document into the documents table.
+ * Returns the document's id so callers can attach document-scoped state.
  */
-export declare function insertDocument(db: Database, collectionName: string, path: string, title: string, hash: string, createdAt: string, modifiedAt: string): void;
+export declare function insertDocument(db: Database, collectionName: string, path: string, title: string, hash: string, createdAt: string, modifiedAt: string): number;
 /** Insert immutable content and its document row in the same lexical transaction. */
-export declare function insertDocumentWithContent(db: Database, hash: string, content: string, contentCreatedAt: string, collectionName: string, path: string, title: string, documentCreatedAt: string, modifiedAt: string): void;
+export declare function insertDocumentWithContent(db: Database, hash: string, content: string, contentCreatedAt: string, collectionName: string, path: string, title: string, documentCreatedAt: string, modifiedAt: string): number;
 /**
  * Find an active document by collection name and path.
  */
@@ -778,13 +792,6 @@ export declare function chunkDocumentAsync(content: string, maxChars?: number, o
     text: string;
     pos: number;
 }[]>;
-/**
- * Chunk a document by actual token count using the LLM tokenizer.
- * More accurate than character-based chunking but requires async.
- *
- * When filepath and chunkStrategy are provided, uses AST-aware break points
- * for supported code files.
- */
 export declare function chunkDocumentByTokens(content: string, maxTokens?: number, overlapTokens?: number, windowTokens?: number, filepath?: string, chunkStrategy?: ChunkStrategy, signal?: AbortSignal): Promise<{
     text: string;
     pos: number;
@@ -929,9 +936,9 @@ export declare const CJK_LEXICAL_CANDIDATE_DEPTH = 60;
 export declare const CJK_LEXICAL_RRF_WEIGHTS: Readonly<Record<CjkLexicalChannel, number>>;
 export type CollectionFilter = string | readonly string[];
 export type CollectionScope = string | readonly string[] | undefined;
-export declare function searchCharFTS(db: Database, query: string, limit?: number, collectionFilter?: CollectionFilter): SearchResult[];
-export declare function searchFTS(db: Database, query: string, limit?: number, collectionFilter?: CollectionFilter): SearchResult[];
-export declare function searchVec(db: Database, query: string, model: string, limit?: number, collectionFilter?: CollectionFilter, session?: ILLMSession, precomputedEmbedding?: number[], provider?: EmbeddingProvider, authorizeRemoteRequest?: Store["authorizeRemoteRequest"], llmOverride?: LLM): Promise<SearchResult[]>;
+export declare function searchCharFTS(db: Database, query: string, limit?: number, collectionFilter?: CollectionFilter, filter?: MetadataFilter): SearchResult[];
+export declare function searchFTS(db: Database, query: string, limit?: number, collectionFilter?: CollectionScope, filter?: MetadataFilter): SearchResult[];
+export declare function searchVec(db: Database, query: string, model: string, limit?: number, collectionFilter?: CollectionFilter, session?: ILLMSession, precomputedEmbedding?: number[], providerOrLlm?: EmbeddingProvider | LLM, authorizeRemoteRequestOrFilter?: Store["authorizeRemoteRequest"] | MetadataFilter, llmOverride?: LLM, metadataFilter?: MetadataFilter): Promise<SearchResult[]>;
 /**
  * Get all unique content hashes that need embeddings (from active documents).
  * Returns hash, document body, and a sample path for display purposes.
@@ -979,6 +986,7 @@ export declare function deleteExpansionCacheEntry(db: Database, query: string, m
 export declare function rerank(query: string, documents: {
     file: string;
     text: string;
+    title?: string;
 }[], model: string | undefined, db: Database, rerankContext?: string, llmOverride?: LLM): Promise<{
     file: string;
     score: number;
@@ -1104,6 +1112,7 @@ export type ExpansionErrorEvent = {
 export interface HybridQueryOptions {
     collection?: string | readonly string[];
     collections?: readonly string[];
+    filter?: MetadataFilter;
     limit?: number;
     minScore?: number;
     candidateLimit?: number;
@@ -1128,6 +1137,7 @@ export interface HybridQueryResult {
     score: number;
     context: string | null;
     docid: string;
+    metadata: DocumentMetadata;
     explain?: HybridQueryExplain;
 }
 export type RankedListMeta = {
@@ -1163,6 +1173,7 @@ export declare function getHybridRrfWeights(rankedListMeta: RankedListMeta[]): n
 export declare function hybridQuery(store: Store, query: string, options?: HybridQueryOptions): Promise<HybridQueryResult[]>;
 export interface VectorSearchOptions {
     collection?: CollectionFilter;
+    filter?: MetadataFilter;
     limit?: number;
     minScore?: number;
     /** Additional context used only while generating query expansions. */
@@ -1179,6 +1190,7 @@ export interface VectorSearchResult {
     score: number;
     context: string | null;
     docid: string;
+    metadata: DocumentMetadata;
 }
 /**
  * Vector-only semantic search with query expansion.
@@ -1196,6 +1208,7 @@ export declare function vectorSearchQuery(store: Store, query: string, options?:
  */
 export interface StructuredSearchOptions {
     collections?: string[];
+    filter?: MetadataFilter;
     limit?: number;
     minScore?: number;
     candidateLimit?: number;