@equationalapplications/core-llm-wiki 4.6.1 → 4.8.0

package/dist/index.d.ts

@@ -1,532 +1,6 @@
-/**
- * Platform-agnostic SQLite driver interface.
- * Each platform package (wiki-expo, wiki-react) provides an adapter
- * that wraps its native driver behind this interface.
- */
-interface SQLiteAdapter {
-    execAsync(sql: string): Promise<void>;
-    runAsync(sql: string, params?: unknown[]): Promise<{
-        changes: number;
-        lastInsertRowId: number;
-    }>;
-    getAllAsync<T>(sql: string, params?: unknown[]): Promise<T[]>;
-    getFirstAsync<T>(sql: string, params?: unknown[]): Promise<T | null>;
-    withTransactionAsync<T>(fn: () => Promise<T>): Promise<T>;
-    closeAsync(): Promise<void>;
-}
-interface WikiConfig {
-    tablePrefix?: string;
-    maxResults?: number;
-    /** @deprecated Use maxResults */
-    maxFtsResults?: number;
-    pruneEventsAfter?: number;
-    pruneRetainSoftDeletedFor?: number;
-    autoLibrarianThreshold?: number;
-    autoHealThreshold?: number;
-    orphanAfterDays?: number | null;
-    staleInferredAfterDays?: number | null;
-    maxChunkLength?: number;
-    chunkOverlap?: number;
-    chunkConcurrency?: number;
-    /**
-     * Max MiniSearch candidates passed to cosine scoring.
-     * When set, MiniSearch pre-filters before the cosine scan.
-     * Only applies when embed is provided and succeeds.
-     * Default: undefined (full scan).
-     */
-    preFilterLimit?: number;
-    /**
-     * Hybrid blend weight (0.0–1.0).
-     * 0.0 = pure keyword (skips embed() entirely).
-     * 1.0 = pure semantic.
-     * Values outside [0,1] are clamped. Ignored when embed is absent or throws.
-     * Default: undefined (pure semantic when embed provided).
-     */
-    hybridWeight?: number;
-}
-interface ReadOptions {
-    maxResults?: number;
-    /**
-     * undefined → use WikiConfig.preFilterLimit (or no pre-filter if also unset).
-     * null → explicitly disable a config-level preFilterLimit for this call.
-     */
-    preFilterLimit?: number | null;
-    hybridWeight?: number;
-    /**
-     * Per-entity score multiplier for multi-entity reads. Missing entries default to 1.0.
-     * Entities with weight 0 are skipped during scored retrieval unless
-     * `includeZeroWeightEntities` is true; in that case they rank below all finite scores.
-     * Only meaningful when `entityId` is an array; ignored for single-string calls.
-     */
-    tierWeights?: Record<string, number>;
-    /**
-     * When true, entities with a tier weight of 0 are included in scored retrieval
-     * as bottom fillers (ranked below every finite-scored candidate).
-     * When false (default), zero-weight entities are skipped entirely.
-     * Only meaningful when `entityId` is an array; ignored for single-string calls.
-     */
-    includeZeroWeightEntities?: boolean;
-}
-interface WikiFact {
-    id: string;
-    entity_id: string;
-    title: string;
-    body: string;
-    tags: string[];
-    confidence: 'certain' | 'inferred' | 'tentative';
-    /**
-     * Source type of this fact.
-     * - 'immutable_document': From ingestDocument(), cannot be modified by system (librarian/heal).
-     *   Only removable via forget() or replaced via re-ingest.
-     * - 'librarian_inferred': Created by runLibrarian() from events, or by runHeal() when synthesizing new inferred facts.
-     * - 'user_stated': Direct user statement.
-     * - 'user_confirmed': User-confirmed fact.
-     */
-    source_type: 'user_stated' | 'librarian_inferred' | 'user_confirmed' | 'immutable_document';
-    source_hash: string | null;
-    source_ref: string | null;
-    created_at: number;
-    updated_at: number;
-    /**
-     * Raw Float32Array bytes for the fact's embedding vector.
-     * Set when the fact was fetched via exportDump() with blob preservation.
-     * Accepted in importDump() as a real Uint8Array (in-memory round-trip),
-     * a Node.js Buffer JSON shape `{ type: 'Buffer', data: number[] }`,
-     * or a numeric-keyed plain object `{ 0: byte, 1: byte, ... }` produced
-     * by JSON.stringify(Uint8Array).
-     */
-    embedding_blob?: Uint8Array | {
-        type: 'Buffer';
-        data: number[];
-    } | Record<string, number>;
-    last_accessed_at: number | null;
-    access_count: number;
-    deleted_at: number | null;
-}
-interface WikiTask {
-    id: string;
-    entity_id: string;
-    description: string;
-    status: 'pending' | 'in_progress' | 'done' | 'abandoned';
-    priority: number;
-    created_at: number;
-    updated_at: number;
-    resolved_at: number | null;
-    deleted_at: number | null;
-}
-interface WikiEvent {
-    id: string;
-    entity_id: string;
-    event_type: 'observation' | 'decision' | 'action' | 'outcome';
-    summary: string;
-    related_entry_id?: string | null;
-    created_at: number;
-}
-interface WikiCheckpoint {
-    entity_id: string;
-    heal_checkpoint: number;
-    memory_checkpoint: number;
-}
-interface ExtractedFact {
-    title: string;
-    body: string;
-    tags: string[];
-    confidence: 'certain' | 'inferred' | 'tentative';
-}
-interface ExtractedTask {
-    description: string;
-    priority: number;
-}
-interface LLMProvider {
-    /**
-     * Generates text using the developer's LLM of choice.
-     * Expected to return the raw text response (typically a JSON string).
-     */
-    generateText: (params: {
-        systemPrompt: string;
-        userPrompt: string;
-    }) => Promise<string>;
-    /**
-     * Optional. When provided, enables semantic similarity search in `read()`.
-     * Must return a stable-dimension float array for any input text.
-     * Called once per fact on creation/update, and once per `read()` query.
-     * When absent or throws, `read()` falls back to MiniSearch.
-     */
-    embed?: (text: string) => Promise<number[]>;
-}
-/**
- * Result of semantic ranking for a single fact.
- */
-interface VectorRankerSemanticResult {
-    id: string;
-    /** Cosine similarity in [-1, 1] when exact; implementations MAY document other monotonic scales. */
-    semanticScore: number;
-}
-/**
- * Arguments passed to VectorRanker.rankBySimilarity.
- */
-interface VectorRankerRankArgs {
-    entityId: string;
-    /**
-     * Query embedding. Treat as readonly — core provides a defensive copy,
-     * but adapters MUST NOT mutate this array. Mutation can corrupt
-     * WikiMemory's internal vector cache and JS-cosine fallback path.
-     */
-    queryVec: Float32Array | number[];
-    /**
-     * When set (MiniSearch pre-filter path): ranker MUST only produce results for ids in this set.
-     * When omitted (full-entity semantic path): ranker scopes by entityId per its backing store contract.
-     */
-    candidateIds?: readonly string[];
-    /**
-     * Upper bound on how many distinct fact ids should receive a semanticScore in this call.
-     * WikiMemory derives this from maxResults / candidate cardinality / documented oversampling policy.
-     */
-    limit: number;
-}
-/**
- * Optional backend for semantic candidate scoring / top-k retrieval.
- * When omitted, WikiMemory scores rows with embedding_blob / embedding TEXT in JS (cosine).
- */
-interface VectorRanker {
-    /**
-     * Return semantic scores for facts in scope, sorted descending by semanticScore (stable tie-breaking
-     * not required — WikiMemory reapplies existing tie-breakers after blending).
-     * Implementations SHOULD omit facts with no usable vector; callers treat missing ids like today's
-     * "no embedding" rows (pure semantic: -2; hybrid: keyword-only portion).
-     */
-    rankBySimilarity(args: VectorRankerRankArgs): Promise<VectorRankerSemanticResult[]>;
-    /**
-     * Called after a fact's embedding is successfully persisted to embedding_blob (or cleared).
-     * Hosts use this to keep sqlite-vec / external indexes consistent with SQLite as source of truth.
-     *
-     * On deletion paths (forget, prune, hard-delete), core awaits this hook to ensure ANN cleanup
-     * completes before the deletion call resolves (GDPR compliance). Hook failures or timeouts on
-     * those paths reject the deletion call.
-     *
-     * Treat `vector` as readonly — core provides a defensive copy, but adapters MUST NOT mutate.
-     *
-     * Optional: if omitted, hosts MUST document "index rebuilt separately" and accept stale ANN until rebuild.
-     */
-    onEmbeddingPersisted?(event: {
-        entityId: string;
-        factId: string;
-        vector: Float32Array | null;
-    }): void | Promise<void>;
-}
-/**
- * Fallback policy when rankBySimilarity rejects.
- */
-type VectorRankerFallback = 'js-cosine' | 'keyword' | 'empty' | 'throw';
-interface WikiOptions {
-    config?: WikiConfig;
-    llmProvider: LLMProvider;
-    /**
-     * Called when embedding-based retrieval is degraded or unavailable during `read()`.
-     * This can happen when:
-     * - `embed()` throws (e.g. network error, model unavailable) → falls back to keyword search
-     * - `embed()` returns a vector with non-finite values (NaN / Infinity) → falls back to keyword search
-     * - The query vector's dimension doesn't match stored embeddings (model switch;
-     *   resolve by calling `runReembed()`) → falls back to keyword search
-     * - `vectorRanker` returns IDs that don't belong to the requested entity or don't exist
-     *   (ranker integrity issue; returned rows will be filtered out, reducing result count) →
-     *   may still use semantic ranking, but with degraded quality
-     *
-     * `read()` returns results (keyword fallback or degraded semantic) — this is a notification, not an error path.
-     */
-    onRetrievalFallback?: (error: Error) => void;
-    /**
-     * Optional backend for semantic candidate scoring / top-k retrieval.
-     * When omitted, WikiMemory scores rows with embedding_blob / embedding TEXT in JS (cosine).
-     */
-    vectorRanker?: VectorRanker;
-    /**
-     * When rankBySimilarity throws. Default `'js-cosine'`.
-     * Ignored when vectorRanker is undefined.
-     */
-    vectorRankerFallback?: VectorRankerFallback;
-    /**
-     * Called only when rankBySimilarity rejects (after embeddings path succeeded).
-     * Invoked before applying vectorRankerFallback when that policy recovers or before rejecting when policy is 'throw'.
-     */
-    onVectorRankerFallback?: (info: {
-        error: Error;
-        /** Effective policy core will apply for this read (same as WikiOptions.vectorRankerFallback, default js-cosine). */
-        policy: VectorRankerFallback;
-    }) => void;
-    /**
-     * When true: after rankBySimilarity failure, once the recoverable fallback has finished
-     * and read() will resolve, invoke onRetrievalFallback — after onVectorRankerFallback if set.
-     * Ignored when vectorRankerFallback is 'throw'. Default false.
-     */
-    propagateRankerFailureToRetrievalFallback?: boolean;
-    /**
-     * When true (default), sanitize ranker errors before exposing via error.cause
-     * to prevent credential leakage in host telemetry. Disable only when you
-     * control the ranker implementation.
-     *
-     * Sanitization replaces error message/stack with a generic message preserving
-     * only the error type (constructor name).
-     */
-    sanitizeRankerErrors?: boolean;
-    /**
-     * Timeout (ms) for onEmbeddingPersisted hook on GDPR deletion paths
-     * (forget, _doPrune). Hook must complete within this window or the
-     * deletion operation rejects. Default 30000.
-     * Lower for interactive deletes; raise for slow remote ANN backends.
-     */
-    deletionHookTimeoutMs?: number;
-    /**
-     * Escape hatch: skip onEmbeddingPersisted on deletion paths entirely.
-     * Use ONLY when the ANN backend is permanently decommissioned. Vectors
-     * orphaned in the (unreachable) external index are accepted as a tradeoff.
-     * NOT GDPR-safe for live indexes. Default false.
-     */
-    forceDeleteIgnoreRankerHook?: boolean;
-}
-interface MemoryBundle {
-    facts: WikiFact[];
-    tasks: WikiTask[];
-    events: WikiEvent[];
-    factScores?: Record<string, number>;
-    metadata?: {
-        query: string;
-        entityIds: string[];
-        tierWeights?: Record<string, number>;
-    };
-}
-interface MemoryDump {
-    generatedAt: number;
-    entities: Record<string, MemoryBundle>;
-}
-interface FormattedMemoryDump {
-    manifest: string;
-    files: Array<{
-        name: string;
-        content: string;
-    }>;
-}
-interface FormatContextOptions {
-    format?: 'markdown' | 'plain';
-    maxFacts?: number;
-    maxTasks?: number;
-    maxEvents?: number;
-    includeConfidence?: boolean;
-    includeTags?: boolean;
-    includeEntityIds?: boolean;
-    includeFactScores?: boolean;
-    factWeights?: {
-        confidence?: number;
-        accessCount?: number;
-        recency?: number;
-    };
-}
-interface EntityStatus {
-    ingesting: boolean;
-    librarian: boolean;
-    heal: boolean;
-}
-/**
- * All operations that can appear in a {@link WikiBusyError}.
- *
- * @remarks **Breaking change from v2.x** — the union previously only contained
- * `'ingest' | 'librarian' | 'heal' | 'prune' | 'reembed'`. The values `'import'`
- * and `'forget'` were added in v3.0. Exhaustive `switch` / narrowing on this type
- * must be updated (or given a `default` arm) to compile without errors.
- */
-type WikiBusyOperation = 'ingest' | 'librarian' | 'heal' | 'prune' | 'reembed' | 'import' | 'forget';
-/**
- * Thrown when a background mutator is already running for the requested entity.
- */
-declare class WikiBusyError extends Error {
-    readonly operation: WikiBusyOperation;
-    readonly entityId: string;
-    constructor(operation: WikiBusyOperation, entityId: string);
-}
-declare class PrunePartialFailureError extends Error {
-    readonly deleted: number;
-    readonly failedAt: string;
-    readonly remaining: number;
-    readonly deletedTasks: number;
-    readonly deletedEvents: number;
-    readonly cause: Error;
-    constructor(deleted: number, failedAt: string, remaining: number, cause: Error, deletedTasks?: number, deletedEvents?: number);
-}
-
-declare class WikiMemory {
-    private db;
-    private prefix;
-    private options;
-    private entryRepo;
-    private activeMaintenanceJobs;
-    private activeIngestJobs;
-    private statusSubscribers;
-    private miniSearch;
-    private miniSearchEntryIdsByEntity;
-    /**
-     * Maximum number of entities whose parsed embedding vectors are held in
-     * memory. This cap is intentionally conservative so the cache remains safe
-     * on memory-constrained runtimes (e.g., mobile/Expo).
-     */
-    private static readonly MAX_VECTOR_CACHE_ENTITIES;
-    /**
-     * Maximum number of fact vectors cached per entity. Keep this high enough to
-     * preserve the parsed-embedding reuse optimization for common mid-sized
-     * entities while still maintaining a bounded memory footprint.
-     */
-    private static readonly MAX_VECTOR_CACHE_FACTS_PER_ENTITY;
-    private vectorCache;
-    private normalizeMiniSearchRow;
-    private rebuildMiniSearchIndex;
-    private storeEmbeddingDimension;
-    /**
-     * After a successful runReembed(), promote the pending `embedding_dimension_mismatch`
-     * value to the canonical `embedding_dimension` key and clear the mismatch flag.
-     * This ensures future read() calls use embedding-based retrieval rather than staying
-     * stuck on the MiniSearch fallback.
-     */
-    private _reconcileEmbeddingDimension;
-    private embedFact;
-    private _librarianKey;
-    private _healKey;
-    private _warnCrossEntityCollision;
-    /** Maps pre-rename enum strings from older dumps to current source_type values. */
-    private _normalizeImportedSourceType;
-    private assertNoLegacySourceTypes;
-    private _notifyEmbeddingPersisted;
-    /**
-     * GDPR-critical variant: awaits the hook with a timeout and rethrows failures.
-     * Use ONLY on deletion paths. forget() calls after soft-delete UPDATE; runPrune()
-     * calls before hard DELETE. For best-effort sync, use _notifyEmbeddingPersisted.
-     */
-    private _notifyEmbeddingPersistedOrThrow;
-    constructor(db: SQLiteAdapter, options: WikiOptions);
-    setup(): Promise<void>;
-    hasChanged(entityId: string, sourceRef: string, sourceHash: string): Promise<boolean>;
-    private _pruneKey;
-    private _reembedKey;
-    private _globalReembedKey;
-    private _importKey;
-    private _globalImportKey;
-    private _forgetKey;
-    private _isReembedActive;
-    private _isImportActiveFor;
-    private _isForgetActiveFor;
-    /** Returns true if any maintenance job has the given operation suffix (e.g. ':prune'). */
-    private _isAnyMaintenanceActiveWithSuffix;
-    /** Returns true if any ingest job is active for the given entity. */
-    private _isIngestActiveFor;
-    private _copyEntityStatus;
-    private _notifyStatusSubscribers;
-    private _validatePruneDuration;
-    runPrune(entityId: string, options?: {
-        retainSoftDeletedFor?: number | null;
-        retainEventsFor?: number | null;
-        vacuum?: boolean;
-    }): Promise<{
-        entries: number;
-        tasks: number;
-        events: number;
-    }>;
-    read(entityId: string | string[], query: string, options?: ReadOptions): Promise<MemoryBundle>;
-    /**
-     * Returns entity IDs that will participate in scored retrieval.
-     * Excludes zero-weight entities unless includeZeroWeightEntities is true.
-     */
-    private _filterScoredEntities;
-    /**
-     * Stable tie-break sort: score desc → access_count desc → updated_at desc → id asc.
-     */
-    private _tieBreakSort;
-    /**
-     * Comparator for score + deterministic tie-break fields.
-     * Negative return means "a ranks ahead of b" for descending score order.
-     */
-    private _compareScoredRows;
-    /**
-     * Build SQL IN clause with placeholders for multiple entity IDs.
-     */
-    private _entityInClause;
-    /**
-     * Hydrate full facts by ID. Pass scopedEntityIds to restrict to requested namespaces in SQL
-     * (defense-in-depth against a rogue VectorRanker returning cross-entity IDs).
-     */
-    private _hydrateFactsByIds;
-    /**
-     * Strip potentially sensitive data from ranker errors before exposing to host callbacks.
-     * Preserves error type for debugging but removes message/stack that may contain credentials.
-     * Recursively sanitizes one level of .cause; deeper chains collapse to type only.
-     */
-    private _sanitizeRankerError;
-    /**
-     * Score candidate rows using in-process JS cosine similarity.
-     * Applies hybrid blending (if weight set) and tie-break sorting before returning.
-     */
-    private _rankWithJsCosine;
-    /**
-     * Delegate semantic ranking to the injected VectorRanker.
-     * Caller should pass an oversampledLimit to preserve recall after re-ranking.
-     * Returns scored results ready for hybrid blending and tie-break sorting.
-     */
-    private _rankWithVectorRanker;
-    getMemoryBundle(entityId: string): Promise<MemoryBundle>;
-    write(entityId: string, event: Omit<WikiEvent, 'id' | 'entity_id' | 'created_at'>): Promise<void>;
-    private runLibrarianThenMaybeHeal;
-    private _doRunLibrarian;
-    private _doRunHeal;
-    runLibrarian(entityId: string): Promise<void>;
-    runHeal(entityId: string): Promise<void>;
-    runReembed(entityId?: string, opts?: {
-        force?: boolean;
-        skipExisting?: boolean;
-    }): Promise<{
-        embedded: number;
-        skipped: number;
-        failed: number;
-    }>;
-    getEntityStatus(entityId: string): EntityStatus;
-    /**
-     * Subscribe to {@link EntityStatus} changes for a single entity. The callback
-     * is invoked synchronously once with the current status before this method
-     * returns, then again on every transition where any of `ingesting`,
-     * `librarian`, or `heal` flips. No polling, no duplicate snapshots.
-     *
-     * Returns an idempotent unsubscribe function.
-     *
-     * See also {@link getEntityStatus} for a synchronous point-in-time read.
-     */
-    subscribeEntityStatus(entityId: string, callback: (status: EntityStatus) => void): () => void;
-    clearVectorCache(): void;
-    private _getFullBundle;
-    exportDump(entityIds?: string[]): Promise<MemoryDump>;
-    importDump(dump: MemoryDump, opts?: {
-        merge?: boolean;
-    }): Promise<void>;
-    private _doImportEntity;
-    forget(entityId: string, params: {
-        entryId?: string;
-        taskId?: string;
-        sourceRef?: string;
-        sourceHash?: string;
-        clearAll?: boolean;
-    }): Promise<{
-        deleted: {
-            entries: number;
-            tasks: number;
-        };
-    }>;
-    ingestDocument(entityId: string, params: {
-        sourceRef: string;
-        sourceHash: string;
-        documentChunk: string;
-        maxChunkLength?: number;
-        chunkOverlap?: number;
-        chunkConcurrency?: number;
-    }): Promise<{
-        truncated: boolean;
-        chunks: number;
-    }>;
-}
+import { M as MemoryBundle, F as FormatContextOptions, a as MemoryDump, b as FormattedMemoryDump, R as ReadOptions, S as SQLiteAdapter, W as WikiOptions, c as WikiMemory } from './testing-hfpeX01Q.js';
+export { E as EntityStatus, d as ExtractedFact, e as ExtractedTask, H as HOOK_TIMEOUT_MARKER, L as LLMProvider, P as PromptOverrides, f as PromptService, g as PrunePartialFailureError, V as VectorRanker, h as VectorRankerFallback, i as VectorRankerRankArgs, j as VectorRankerSemanticResult, k as WikiBusyError, l as WikiBusyOperation, m as WikiCheckpoint, n as WikiConfig, o as WikiEvent, p as WikiFact, q as WikiMemoryTestAccess, r as WikiTask } from './testing-hfpeX01Q.js';
+import 'minisearch';
 
 declare function formatContext(bundle: MemoryBundle, options?: FormatContextOptions): string;
 
@@ -558,4 +32,4 @@ declare function mapLibrarianOptionsToReadOptions(options: LibrarianOptions): Pi
 
 declare function createWiki(db: SQLiteAdapter, options: WikiOptions): WikiMemory;
 
-export { DEFAULT_LIBRARIAN_SYNTHESIS_PROMPT, type EntityStatus, type ExtractedFact, type ExtractedTask, type FormatContextOptions, type FormattedMemoryDump, type LLMProvider, type LibrarianOptions, type LibrarianPromptVariables, type MemoryBundle, type MemoryDump, PrunePartialFailureError, type ReadOptions, type SQLiteAdapter, type VectorRanker, type VectorRankerFallback, type VectorRankerRankArgs, type VectorRankerSemanticResult, WikiBusyError, type WikiBusyOperation, type WikiCheckpoint, type WikiConfig, type WikiEvent, type WikiFact, WikiMemory, type WikiOptions, type WikiTask, createWiki, formatContext, formatMemoryDump, hydrateLibrarianPrompt, mapLibrarianOptionsToReadOptions, parseEmbedding, validateLibrarianPromptTemplate };
+export { DEFAULT_LIBRARIAN_SYNTHESIS_PROMPT, FormatContextOptions, FormattedMemoryDump, type LibrarianOptions, type LibrarianPromptVariables, MemoryBundle, MemoryDump, ReadOptions, SQLiteAdapter, WikiMemory, WikiOptions, createWiki, formatContext, formatMemoryDump, hydrateLibrarianPrompt, mapLibrarianOptionsToReadOptions, parseEmbedding, validateLibrarianPromptTemplate };