@equationalapplications/core-llm-wiki 7.9.1 → 7.10.0

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

@@ -314,6 +314,19 @@ interface WikiConfig {
     ontology?: OntologyConfig;
     /** Default node cap for traverseGraph(), unless overridden per-call. Default 20. */
     maxTraversalNodes?: number;
+    /**
+     * Keyword-index backend (#257).
+     * - `'fts5'`: always use SQLite FTS5; `setup()` throws if the adapter's SQLite lacks FTS5 or json1.
+     * - `'minisearch'`: always use the in-RAM MiniSearch index. Memory grows with stored text.
+     * - `'auto'`: probe at `setup()`; use FTS5 when present, else MiniSearch.
+     *
+     * FTS5 keeps its index inside the database file, fed by triggers on the
+     * entries table, so memory stays flat at any size. The first `setup()` that
+     * attaches FTS5 to an existing database rebuilds the index in one
+     * transaction, holding the write lock for its whole duration.
+     * @default 'minisearch'
+     */
+    indexStrategy?: 'fts5' | 'minisearch' | 'auto';
     /** Default minimum confidence tier for discovered traversal nodes. Default 'tentative'. */
     minTraversalConfidence?: 'certain' | 'inferred' | 'tentative';
     /** Default traversal direction. Default 'both'. */
@@ -2022,6 +2035,22 @@ interface IndexStrategy {
      * Returning `undefined` means "unknown — take the rebuild path".
      */
     hasIndexedEntity?(entityId: string): boolean | undefined;
+    /**
+     * Create or verify the strategy's backing schema and run state changes.
+     * Called once by `createIndexStrategy`, before the strategy is installed.
+     */
+    init?(): Promise<void>;
+    /**
+     * Apply every change recorded in the strategy's durable ledger, in bounded
+     * chunks. A strategy that implements this keeps itself consistent with
+     * SQLite on its own: `SearchService` routes every sync to `drain()` and
+     * never feeds it rows (spec 2026-10-05 §PR-2 revision). MUST NOT be
+     * called from inside a `withTransactionAsync` callback; it opens its own
+     * transactions.
+     */
+    drain?(): Promise<void>;
+    /** Rebuild entirely in SQL from the source tables; no rows pass through JS. */
+    rebuildFromSource?(): Promise<void>;
 }
 
 interface ScoredRow {
@@ -2089,6 +2118,17 @@ declare class SearchService {
      */
     private staleEpochs;
     constructor(entryRepo: EntryRepository, indexStrategy: IndexStrategy);
+    /**
+     * Install the strategy resolved by `WikiMemory.setup()`. Before setup, the
+     * service runs on an empty MiniSearch placeholder, as it always has.
+     */
+    setIndexStrategy(strategy: IndexStrategy): void;
+    /**
+     * One serialized drain turn for strategies with a durable ledger. Like
+     * sync(), it never rejects: the keyword index is rebuildable, and a failed
+     * drain leaves the ledger rows in place for the next turn.
+     */
+    private drainTurn;
     /**
      * Rebuilds the search index and clears the vector cache for a given entity.
      * A direct replacement for manually syncing state after a DB transaction.
@@ -3611,6 +3651,11 @@ declare class WikiMemory {
      * entity stays stale and the next call retries it. Does not compute
      * embeddings; that remains the maintenance sweep's job.
      *
+     * With the FTS5 index strategy this drains the index ledger in its own
+     * transactions, so it MUST be called after the host transaction commits,
+     * never from inside a `withTransactionAsync` callback. Calling it inside
+     * one waits on the transaction mutex that the callback holds.
+     *
      * @throws {TypeError} when `entityId` is given but is not a non-empty string.
      */
     syncSearchIndex(entityId?: string): Promise<void>;

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

@@ -314,6 +314,19 @@ interface WikiConfig {
     ontology?: OntologyConfig;
     /** Default node cap for traverseGraph(), unless overridden per-call. Default 20. */
     maxTraversalNodes?: number;
+    /**
+     * Keyword-index backend (#257).
+     * - `'fts5'`: always use SQLite FTS5; `setup()` throws if the adapter's SQLite lacks FTS5 or json1.
+     * - `'minisearch'`: always use the in-RAM MiniSearch index. Memory grows with stored text.
+     * - `'auto'`: probe at `setup()`; use FTS5 when present, else MiniSearch.
+     *
+     * FTS5 keeps its index inside the database file, fed by triggers on the
+     * entries table, so memory stays flat at any size. The first `setup()` that
+     * attaches FTS5 to an existing database rebuilds the index in one
+     * transaction, holding the write lock for its whole duration.
+     * @default 'minisearch'
+     */
+    indexStrategy?: 'fts5' | 'minisearch' | 'auto';
     /** Default minimum confidence tier for discovered traversal nodes. Default 'tentative'. */
     minTraversalConfidence?: 'certain' | 'inferred' | 'tentative';
     /** Default traversal direction. Default 'both'. */
@@ -2022,6 +2035,22 @@ interface IndexStrategy {
      * Returning `undefined` means "unknown — take the rebuild path".
      */
     hasIndexedEntity?(entityId: string): boolean | undefined;
+    /**
+     * Create or verify the strategy's backing schema and run state changes.
+     * Called once by `createIndexStrategy`, before the strategy is installed.
+     */
+    init?(): Promise<void>;
+    /**
+     * Apply every change recorded in the strategy's durable ledger, in bounded
+     * chunks. A strategy that implements this keeps itself consistent with
+     * SQLite on its own: `SearchService` routes every sync to `drain()` and
+     * never feeds it rows (spec 2026-10-05 §PR-2 revision). MUST NOT be
+     * called from inside a `withTransactionAsync` callback; it opens its own
+     * transactions.
+     */
+    drain?(): Promise<void>;
+    /** Rebuild entirely in SQL from the source tables; no rows pass through JS. */
+    rebuildFromSource?(): Promise<void>;
 }
 
 interface ScoredRow {
@@ -2089,6 +2118,17 @@ declare class SearchService {
      */
     private staleEpochs;
     constructor(entryRepo: EntryRepository, indexStrategy: IndexStrategy);
+    /**
+     * Install the strategy resolved by `WikiMemory.setup()`. Before setup, the
+     * service runs on an empty MiniSearch placeholder, as it always has.
+     */
+    setIndexStrategy(strategy: IndexStrategy): void;
+    /**
+     * One serialized drain turn for strategies with a durable ledger. Like
+     * sync(), it never rejects: the keyword index is rebuildable, and a failed
+     * drain leaves the ledger rows in place for the next turn.
+     */
+    private drainTurn;
     /**
      * Rebuilds the search index and clears the vector cache for a given entity.
      * A direct replacement for manually syncing state after a DB transaction.
@@ -3611,6 +3651,11 @@ declare class WikiMemory {
      * entity stays stale and the next call retries it. Does not compute
      * embeddings; that remains the maintenance sweep's job.
      *
+     * With the FTS5 index strategy this drains the index ledger in its own
+     * transactions, so it MUST be called after the host transaction commits,
+     * never from inside a `withTransactionAsync` callback. Calling it inside
+     * one waits on the transaction mutex that the callback holds.
+     *
      * @throws {TypeError} when `entityId` is given but is not a non-empty string.
      */
     syncSearchIndex(entityId?: string): Promise<void>;

package/dist/testing.d.mts

@@ -1,2 +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-Bf6etdUy.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-SxCsMt1q.mjs';
 import '@equationalapplications/core-okf';

package/dist/testing.d.ts

@@ -1,2 +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-Bf6etdUy.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-SxCsMt1q.js';
 import '@equationalapplications/core-okf';

package/dist/testing.js

@@ -5452,6 +5452,33 @@ var _SearchService = class _SearchService {
     this.staleEpochs = /* @__PURE__ */ new Map();
     this.indexStrategy = indexStrategy;
   }
+  /**
+   * Install the strategy resolved by `WikiMemory.setup()`. Before setup, the
+   * service runs on an empty MiniSearch placeholder, as it always has.
+   */
+  setIndexStrategy(strategy) {
+    this.indexStrategy = strategy;
+  }
+  /**
+   * One serialized drain turn for strategies with a durable ledger. Like
+   * sync(), it never rejects: the keyword index is rebuildable, and a failed
+   * drain leaves the ledger rows in place for the next turn.
+   */
+  drainTurn(entityId) {
+    const work = this.syncChain.then(async () => {
+      try {
+        try {
+          await this.indexStrategy.drain();
+        } finally {
+          this.evictCache(entityId);
+        }
+      } catch (err) {
+        console.warn(`[WikiMemory] search index drain failed for ${entityId ?? "*"}:`, err);
+      }
+    });
+    this.syncChain = work;
+    return work;
+  }
   /**
    * Rebuilds the search index and clears the vector cache for a given entity.
    * A direct replacement for manually syncing state after a DB transaction.
@@ -5461,6 +5488,7 @@ var _SearchService = class _SearchService {
    * correct failure mode and killing the host process is not.
    */
   async sync(entityId) {
+    if (this.indexStrategy.drain) return this.drainTurn(entityId);
     const work = this.syncChain.then(async () => {
       try {
         try {
@@ -5503,6 +5531,7 @@ var _SearchService = class _SearchService {
    * already queued on the chain.
    */
   async syncEntries(entityId, ids) {
+    if (this.indexStrategy.drain) return this.drainTurn(entityId);
     const uniqueIds = [...new Set(ids)];
     const indexed = this.indexStrategy.hasIndexedEntity?.(entityId);
     if (uniqueIds.length === 0 && !this.staleEntities.has(entityId) && indexed === true) {
@@ -5542,6 +5571,7 @@ var _SearchService = class _SearchService {
    * cannot index itself, such as upsertGraph inside a host transaction.
    */
   markStale(entityId) {
+    if (this.indexStrategy.drain) return;
     this.staleEntities.add(entityId);
     this.staleEpochs.set(entityId, (this.staleEpochs.get(entityId) ?? 0) + 1);
   }
@@ -5552,6 +5582,7 @@ var _SearchService = class _SearchService {
    * stale it resolves at once, without waiting on work already on the chain.
    */
   async syncStale() {
+    if (this.indexStrategy.drain) return this.drainTurn();
     const ids = [...this.staleEntities];
     await Promise.all(ids.map((id) => this.syncEntries(id, [])));
   }