@equationalapplications/core-llm-wiki 7.9.0 → 7.9.2

package/dist/{testing-Kb1uVj1E.d.mts → testing-Bf6etdUy.d.mts}

@@ -1,5 +1,4 @@
 import { OkfSource, OkfVerifiedEntry, OkfSourceUsageWindow } from '@equationalapplications/core-okf';
-import { SearchResult } from 'minisearch';
 
 /**
  * Platform-agnostic SQLite driver interface.
@@ -1923,6 +1922,108 @@ declare class MetadataRepository extends BaseRepository {
     mergeManifestUpdates(entityId: string, updates: OntologyUpdates, tx: SQLiteAdapter): Promise<OntologyManifest>;
 }
 
+/**
+ * One document that both keyword-index strategies must understand. Both
+ * implementations expect `tags` to be a single string with the JSON array's
+ * tokens space-joined (see `toIndexDoc` in utils/indexDoc.ts). The exact token
+ * shape is strategy-private — callers do not see it.
+ */
+interface IndexDocument {
+    id: string;
+    entity_id: string;
+    title: string;
+    body: string;
+    tags: string;
+}
+interface IndexSearchOptions {
+    /** Empty array means "no entities match"; strategy returns []. */
+    entityIds: string[];
+    /** Upper bound on results returned. Strategy MUST return ≤ `limit`. */
+    limit: number;
+    /** Optional pre-filter cap used by hybrid retrieval. */
+    preFilterLimit?: number;
+}
+interface IndexSearchResult {
+    id: string;
+    /**
+     * Strategy-native relevance: finite, non-negative, higher is better,
+     * comparable only within one result set. Not normalized —
+     * `SearchService.getKeywordScores` divides by `max(1, top)` for the hybrid
+     * blend, and `searchKeyword` passes scores through unscaled. SearchService
+     * drops any result whose score is not finite.
+     */
+    score: number;
+    /**
+     * The entity id this search result belongs to. Populated from
+     * `IndexDocument.entity_id` by the strategy on every result.
+     */
+    entity_id: string;
+}
+/**
+ * Keyword-index abstraction. The strategy owns its own backing store
+ * (in-RAM MiniSearch vs on-disk FTS5) and is responsible for keeping it
+ * consistent with the rows it has been told to write. The strategy also owns
+ * the per-entity id bookkeeping — `SearchService` never sees the ids, only
+ * an indexed-or-not probe.
+ *
+ * Concurrency: writes are called from serialized turns on
+ * `SearchService.syncChain`, but searches are not, so each write method MUST
+ * apply as one step — a concurrent `search()` sees the index wholly before or
+ * wholly after it, never between its removal and its insertion. MiniSearch
+ * gets this by never awaiting inside a write; FTS5 by one transaction per
+ * write. Strategies MUST NOT spawn background work.
+ */
+interface IndexStrategy {
+    /**
+     * Replace documents under `entityId`: remove the given `ids` only if they
+     * are currently tracked under `entityId` (ids under other entities and ids
+     * the strategy never indexed are silently ignored), then upsert
+     * `documents` by id. The strategy owns its id-tracking structure; callers
+     * do not see it. Used for incremental sync.
+     *
+     * Argument order is `(entityId, ids, documents)` so the FTS5 SQL
+     * `DELETE … WHERE entity_id = ? AND id IN (…)` matches the call shape.
+     */
+    replace(entityId: string, ids: readonly string[], documents: readonly IndexDocument[]): Promise<void>;
+    /**
+     * Drop every document currently tracked under `entityId`, then add
+     * `documents` (all of which belong to `entityId`). The entity stays
+     * registered as indexed, even when `documents` is empty — `hasIndexedEntity`
+     * continues to return `true` so the next incremental sync can take the
+     * fast path. Used for per-entity rebuilds.
+     */
+    replaceEntity(entityId: string, documents: readonly IndexDocument[]): Promise<void>;
+    /**
+     * Empty the entire index, then add `documents`. After this call, no entity
+     * is registered as indexed (`hasIndexedEntity` returns `false` for every
+     * entity). Used for global rebuilds and clears.
+     */
+    replaceAll(documents: readonly IndexDocument[]): Promise<void>;
+    /**
+     * Search the index, best match first. If `preFilterLimit` is set, the
+     * strategy MAY return up to `preFilterLimit` candidates before the `limit`
+     * cap is applied (hybrid retrieval uses this to over-fetch candidates for
+     * downstream vector blending). Score semantics are in `IndexSearchResult`.
+     */
+    search(query: string, options: IndexSearchOptions): Promise<IndexSearchResult[]>;
+    /**
+     * Strategy-internal cleanup. For MiniSearch, this is the explicit vacuum
+     * that `syncEntries` invokes after a discard-bearing turn (#64). FTS5 has
+     * no equivalent; the default implementation is a no-op.
+     */
+    vacuum?(): Promise<void>;
+    /**
+     * `true` when `entityId` has been indexed at least once under the current
+     * strategy state; `false` otherwise. `SearchService.syncEntries` uses this
+     * to choose between the empty-ids no-op fast path and the full-rebuild
+     * fallback. Implementations MUST return `false` after `replaceAll([])` and
+     * MUST return `true` after a `replace`/`replaceEntity` that wrote at least
+     * one document (including `replace(entityId, [], [])` for tracking alone).
+     * Returning `undefined` means "unknown — take the rebuild path".
+     */
+    hasIndexedEntity?(entityId: string): boolean | undefined;
+}
+
 interface ScoredRow {
     id: string;
     entity_id: string;
@@ -1961,8 +2062,7 @@ declare class SearchService {
      * entities while still maintaining a bounded memory footprint.
      */
     private static readonly MAX_VECTOR_CACHE_FACTS_PER_ENTITY;
-    private miniSearch;
-    private miniSearchEntryIdsByEntity;
+    private indexStrategy;
     private vectorCache;
     /**
      * Serializes rebuilds. `rebuildIndex` awaits a repository read between
@@ -1988,19 +2088,12 @@ declare class SearchService {
      * its flag must outlive the turn (#233 review).
      */
     private staleEpochs;
-    constructor(entryRepo: EntryRepository);
-    /**
-     * A fresh index with the production options. clearAll() swaps one in because
-     * MiniSearch.removeAll() empties the index but leaves dirtCount (and its
-     * vacuum bookkeeping) at its old value, which would trip syncEntries'
-     * conditional vacuum early after a clear.
-     */
-    private createMiniSearch;
+    constructor(entryRepo: EntryRepository, indexStrategy: IndexStrategy);
     /**
      * Rebuilds the search index and clears the vector cache for a given entity.
      * A direct replacement for manually syncing state after a DB transaction.
      *
-     * Rebuilds are serialized per instance and never reject: the MiniSearch index
+     * Rebuilds are serialized per instance and never reject: the keyword index
      * is a rebuildable cache over SQLite, so degraded keyword search is the
      * correct failure mode and killing the host process is not.
      */
@@ -2038,30 +2131,36 @@ declare class SearchService {
     /**
      * Fully resets the search service.
      */
-    clearAll(): void;
+    clearAll(): Promise<void>;
     /**
-     * Executes a keyword search against the active MiniSearch index.
+     * Executes a keyword search against the active index strategy.
      */
-    searchKeyword(query: string, entityIds: string[], limit: number): SearchResult[];
+    searchKeyword(query: string, entityIds: string[], limit: number): Promise<IndexSearchResult[]>;
     /**
-     * Pre-fetches MiniSearch scores for candidate hydration, used during hybrid weighting.
+     * Pre-fetches keyword scores for candidate hydration, used during hybrid weighting.
      */
-    getMiniSearchScores(query: string, entityIds: string[], preFilterLimit?: number): Map<string, number>;
+    getKeywordScores(query: string, entityIds: string[], preFilterLimit?: number): Promise<Map<string, number>>;
     /**
      * Score candidate rows using in-process JS cosine similarity.
      * Applies hybrid blending (if weight set) and tie-break sorting before returning.
      */
     rankSemantic(args: RankSemanticArgs): Promise<ScoredRow[]>;
+    /**
+     * Rebuild a single entity's index from scratch. Reads every row for
+     * `entityId` from the repository (already filtered by `deleted_at IS NULL`)
+     * and hands the lot to `indexStrategy.replaceEntity`, which owns the
+     * drop-then-add bookkeeping so callers don't need to know the strategy's
+     * id-tracking shape.
+     */
     private rebuildIndex;
-    private normalizeMiniSearchRow;
     private _tieBreakSort;
     private _compareScoredRows;
     /**
-     * MiniSearch breaks equal-score ties by internal insertion order, which
-     * syncEntries changes: a discarded-and-re-added id moves to the end. Every
-     * caller truncates these results to a limit, so which ids survive a tie at
-     * the boundary must not depend on write history. Re-sort exact score ties
-     * by id — the same final tie-break _compareScoredRows applies.
+     * The keyword index breaks equal-score ties by internal insertion order,
+     * which syncEntries changes: a discarded-and-re-added id moves to the end.
+     * Every caller truncates these results to a limit, so which ids survive a
+     * tie at the boundary must not depend on write history. Re-sort exact
+     * score ties by id — the same final tie-break _compareScoredRows applies.
      */
     private _compareSearchResults;
 }

package/dist/{testing-Kb1uVj1E.d.ts → testing-Bf6etdUy.d.ts}

@@ -1,5 +1,4 @@
 import { OkfSource, OkfVerifiedEntry, OkfSourceUsageWindow } from '@equationalapplications/core-okf';
-import { SearchResult } from 'minisearch';
 
 /**
  * Platform-agnostic SQLite driver interface.
@@ -1923,6 +1922,108 @@ declare class MetadataRepository extends BaseRepository {
     mergeManifestUpdates(entityId: string, updates: OntologyUpdates, tx: SQLiteAdapter): Promise<OntologyManifest>;
 }
 
+/**
+ * One document that both keyword-index strategies must understand. Both
+ * implementations expect `tags` to be a single string with the JSON array's
+ * tokens space-joined (see `toIndexDoc` in utils/indexDoc.ts). The exact token
+ * shape is strategy-private — callers do not see it.
+ */
+interface IndexDocument {
+    id: string;
+    entity_id: string;
+    title: string;
+    body: string;
+    tags: string;
+}
+interface IndexSearchOptions {
+    /** Empty array means "no entities match"; strategy returns []. */
+    entityIds: string[];
+    /** Upper bound on results returned. Strategy MUST return ≤ `limit`. */
+    limit: number;
+    /** Optional pre-filter cap used by hybrid retrieval. */
+    preFilterLimit?: number;
+}
+interface IndexSearchResult {
+    id: string;
+    /**
+     * Strategy-native relevance: finite, non-negative, higher is better,
+     * comparable only within one result set. Not normalized —
+     * `SearchService.getKeywordScores` divides by `max(1, top)` for the hybrid
+     * blend, and `searchKeyword` passes scores through unscaled. SearchService
+     * drops any result whose score is not finite.
+     */
+    score: number;
+    /**
+     * The entity id this search result belongs to. Populated from
+     * `IndexDocument.entity_id` by the strategy on every result.
+     */
+    entity_id: string;
+}
+/**
+ * Keyword-index abstraction. The strategy owns its own backing store
+ * (in-RAM MiniSearch vs on-disk FTS5) and is responsible for keeping it
+ * consistent with the rows it has been told to write. The strategy also owns
+ * the per-entity id bookkeeping — `SearchService` never sees the ids, only
+ * an indexed-or-not probe.
+ *
+ * Concurrency: writes are called from serialized turns on
+ * `SearchService.syncChain`, but searches are not, so each write method MUST
+ * apply as one step — a concurrent `search()` sees the index wholly before or
+ * wholly after it, never between its removal and its insertion. MiniSearch
+ * gets this by never awaiting inside a write; FTS5 by one transaction per
+ * write. Strategies MUST NOT spawn background work.
+ */
+interface IndexStrategy {
+    /**
+     * Replace documents under `entityId`: remove the given `ids` only if they
+     * are currently tracked under `entityId` (ids under other entities and ids
+     * the strategy never indexed are silently ignored), then upsert
+     * `documents` by id. The strategy owns its id-tracking structure; callers
+     * do not see it. Used for incremental sync.
+     *
+     * Argument order is `(entityId, ids, documents)` so the FTS5 SQL
+     * `DELETE … WHERE entity_id = ? AND id IN (…)` matches the call shape.
+     */
+    replace(entityId: string, ids: readonly string[], documents: readonly IndexDocument[]): Promise<void>;
+    /**
+     * Drop every document currently tracked under `entityId`, then add
+     * `documents` (all of which belong to `entityId`). The entity stays
+     * registered as indexed, even when `documents` is empty — `hasIndexedEntity`
+     * continues to return `true` so the next incremental sync can take the
+     * fast path. Used for per-entity rebuilds.
+     */
+    replaceEntity(entityId: string, documents: readonly IndexDocument[]): Promise<void>;
+    /**
+     * Empty the entire index, then add `documents`. After this call, no entity
+     * is registered as indexed (`hasIndexedEntity` returns `false` for every
+     * entity). Used for global rebuilds and clears.
+     */
+    replaceAll(documents: readonly IndexDocument[]): Promise<void>;
+    /**
+     * Search the index, best match first. If `preFilterLimit` is set, the
+     * strategy MAY return up to `preFilterLimit` candidates before the `limit`
+     * cap is applied (hybrid retrieval uses this to over-fetch candidates for
+     * downstream vector blending). Score semantics are in `IndexSearchResult`.
+     */
+    search(query: string, options: IndexSearchOptions): Promise<IndexSearchResult[]>;
+    /**
+     * Strategy-internal cleanup. For MiniSearch, this is the explicit vacuum
+     * that `syncEntries` invokes after a discard-bearing turn (#64). FTS5 has
+     * no equivalent; the default implementation is a no-op.
+     */
+    vacuum?(): Promise<void>;
+    /**
+     * `true` when `entityId` has been indexed at least once under the current
+     * strategy state; `false` otherwise. `SearchService.syncEntries` uses this
+     * to choose between the empty-ids no-op fast path and the full-rebuild
+     * fallback. Implementations MUST return `false` after `replaceAll([])` and
+     * MUST return `true` after a `replace`/`replaceEntity` that wrote at least
+     * one document (including `replace(entityId, [], [])` for tracking alone).
+     * Returning `undefined` means "unknown — take the rebuild path".
+     */
+    hasIndexedEntity?(entityId: string): boolean | undefined;
+}
+
 interface ScoredRow {
     id: string;
     entity_id: string;
@@ -1961,8 +2062,7 @@ declare class SearchService {
      * entities while still maintaining a bounded memory footprint.
      */
     private static readonly MAX_VECTOR_CACHE_FACTS_PER_ENTITY;
-    private miniSearch;
-    private miniSearchEntryIdsByEntity;
+    private indexStrategy;
     private vectorCache;
     /**
      * Serializes rebuilds. `rebuildIndex` awaits a repository read between
@@ -1988,19 +2088,12 @@ declare class SearchService {
      * its flag must outlive the turn (#233 review).
      */
     private staleEpochs;
-    constructor(entryRepo: EntryRepository);
-    /**
-     * A fresh index with the production options. clearAll() swaps one in because
-     * MiniSearch.removeAll() empties the index but leaves dirtCount (and its
-     * vacuum bookkeeping) at its old value, which would trip syncEntries'
-     * conditional vacuum early after a clear.
-     */
-    private createMiniSearch;
+    constructor(entryRepo: EntryRepository, indexStrategy: IndexStrategy);
     /**
      * Rebuilds the search index and clears the vector cache for a given entity.
      * A direct replacement for manually syncing state after a DB transaction.
      *
-     * Rebuilds are serialized per instance and never reject: the MiniSearch index
+     * Rebuilds are serialized per instance and never reject: the keyword index
      * is a rebuildable cache over SQLite, so degraded keyword search is the
      * correct failure mode and killing the host process is not.
      */
@@ -2038,30 +2131,36 @@ declare class SearchService {
     /**
      * Fully resets the search service.
      */
-    clearAll(): void;
+    clearAll(): Promise<void>;
     /**
-     * Executes a keyword search against the active MiniSearch index.
+     * Executes a keyword search against the active index strategy.
      */
-    searchKeyword(query: string, entityIds: string[], limit: number): SearchResult[];
+    searchKeyword(query: string, entityIds: string[], limit: number): Promise<IndexSearchResult[]>;
     /**
-     * Pre-fetches MiniSearch scores for candidate hydration, used during hybrid weighting.
+     * Pre-fetches keyword scores for candidate hydration, used during hybrid weighting.
      */
-    getMiniSearchScores(query: string, entityIds: string[], preFilterLimit?: number): Map<string, number>;
+    getKeywordScores(query: string, entityIds: string[], preFilterLimit?: number): Promise<Map<string, number>>;
     /**
      * Score candidate rows using in-process JS cosine similarity.
      * Applies hybrid blending (if weight set) and tie-break sorting before returning.
      */
     rankSemantic(args: RankSemanticArgs): Promise<ScoredRow[]>;
+    /**
+     * Rebuild a single entity's index from scratch. Reads every row for
+     * `entityId` from the repository (already filtered by `deleted_at IS NULL`)
+     * and hands the lot to `indexStrategy.replaceEntity`, which owns the
+     * drop-then-add bookkeeping so callers don't need to know the strategy's
+     * id-tracking shape.
+     */
     private rebuildIndex;
-    private normalizeMiniSearchRow;
     private _tieBreakSort;
     private _compareScoredRows;
     /**
-     * MiniSearch breaks equal-score ties by internal insertion order, which
-     * syncEntries changes: a discarded-and-re-added id moves to the end. Every
-     * caller truncates these results to a limit, so which ids survive a tie at
-     * the boundary must not depend on write history. Re-sort exact score ties
-     * by id — the same final tie-break _compareScoredRows applies.
+     * The keyword index breaks equal-score ties by internal insertion order,
+     * which syncEntries changes: a discarded-and-re-added id moves to the end.
+     * Every caller truncates these results to a limit, so which ids survive a
+     * tie at the boundary must not depend on write history. Re-sort exact
+     * score ties by id — the same final tie-break _compareScoredRows applies.
      */
     private _compareSearchResults;
 }

package/dist/testing.d.mts

@@ -1,3 +1,2 @@
-export { aB as EmbeddingService, aC as ImportExportService, aD as IngestionService, aE as JobManager, aE as JobManagerType, aF as MaintenanceService, aG as RetrievalService, aH as SearchService, aH as SearchServiceType, ar as WikiMemoryTestAccess, aI as WriteService } from './testing-Kb1uVj1E.mjs';
+export { aB as EmbeddingService, aC as ImportExportService, aD as IngestionService, aE as JobManager, aE as JobManagerType, aF as MaintenanceService, aG as RetrievalService, aH as SearchService, aH as SearchServiceType, ar as WikiMemoryTestAccess, aI as WriteService } from './testing-Bf6etdUy.mjs';
 import '@equationalapplications/core-okf';
-import 'minisearch';

package/dist/testing.d.ts

@@ -1,3 +1,2 @@
-export { aB as EmbeddingService, aC as ImportExportService, aD as IngestionService, aE as JobManager, aE as JobManagerType, aF as MaintenanceService, aG as RetrievalService, aH as SearchService, aH as SearchServiceType, ar as WikiMemoryTestAccess, aI as WriteService } from './testing-Kb1uVj1E.js';
+export { aB as EmbeddingService, aC as ImportExportService, aD as IngestionService, aE as JobManager, aE as JobManagerType, aF as MaintenanceService, aG as RetrievalService, aH as SearchService, aH as SearchServiceType, ar as WikiMemoryTestAccess, aI as WriteService } from './testing-Bf6etdUy.js';
 import '@equationalapplications/core-okf';
-import 'minisearch';