wolbarg 0.3.0 → 0.3.2

package/dist/index.d.ts

@@ -43,7 +43,155 @@ declare const meta: {
 };
 
 /**
- * Public configuration and domain types for Wolbarg v0.2.
+ * Telemetry event types, latency breakdown, and query shapes.
+ * Schema is intentionally extensible for future providers (Postgres, cloud).
+ */
+/** Public operation names recorded as telemetry events. */
+type TelemetryOperation = "remember" | "recall" | "forget" | "compress" | "rememberBatch" | "recallBatch" | "export" | "import" | "checkpoint" | "rollback" | "error" | "startup" | "shutdown" | "ingest" | "history" | "stats" | "clear" | "deleteCheckpoint" | "listCheckpoints" | "getCheckpoint";
+type TelemetryStatus = "ok" | "error" | "cancelled";
+type TelemetryLogLevel = "off" | "error" | "warn" | "info" | "debug" | "trace";
+/** Stage-level latency breakdown recorded on each event. */
+interface LatencyBreakdown {
+    embeddingMs?: number;
+    vectorSearchMs?: number;
+    metadataFilteringMs?: number;
+    rankingMs?: number;
+    serializationMs?: number;
+    databaseWriteMs?: number;
+    databaseReadMs?: number;
+    totalMs: number;
+}
+/** A measured stage within an operation, relative to the operation start. */
+interface StageSpan {
+    name: keyof Omit<LatencyBreakdown, "totalMs"> | (string & {});
+    startMs: number;
+    durationMs: number;
+}
+/** Compact, JSON-safe recall explanation persisted with telemetry events. */
+interface PersistedRecallExplainPayload {
+    enabled: true;
+    providerUsed: string;
+    rankingStrategy: string;
+    signals: {
+        semantic: "enabled";
+        keyword: "enabled" | "disabled" | "unknown";
+        reranker: "enabled" | "disabled" | "unknown";
+        mmr: "enabled" | "disabled";
+        recency: "disabled" | "unknown";
+    };
+    results: Array<{
+        memoryId: string;
+        score: number;
+        distance: number;
+        rankingReason: string;
+        matchedFields: string[];
+        metadataMatch: boolean;
+    }>;
+    searchTimeMs: number;
+    rankingTimeMs: number;
+    totalTimeMs: number;
+}
+/** Input accepted by TelemetryProvider.emit (id / timestamp may be filled). */
+interface TelemetryEventInput {
+    id?: string;
+    timestamp?: string;
+    operation: TelemetryOperation;
+    provider?: string | null;
+    durationMs?: number | null;
+    status: TelemetryStatus;
+    query?: string | null;
+    filters?: unknown;
+    returnedCount?: number | null;
+    memoryIds?: string[] | null;
+    similarityScores?: number[] | null;
+    metadata?: Record<string, unknown> | null;
+    embeddingProvider?: string | null;
+    model?: string | null;
+    error?: string | null;
+    errorStack?: string | null;
+    sessionId: string;
+    traceId: string;
+    parentTraceId?: string | null;
+    organization?: string | null;
+    agentId?: string | null;
+    tags?: string[] | null;
+    checkpointId?: string | null;
+    userMetadata?: Record<string, unknown> | null;
+    extra?: Record<string, unknown> | null;
+    latency?: LatencyBreakdown | null;
+    explain?: PersistedRecallExplainPayload | null;
+    spans?: StageSpan[] | null;
+}
+/** Fully persisted telemetry event row. */
+interface TelemetryEvent extends Required<Pick<TelemetryEventInput, "id" | "timestamp" | "operation" | "status" | "sessionId" | "traceId">> {
+    provider: string | null;
+    durationMs: number | null;
+    query: string | null;
+    filters: unknown;
+    returnedCount: number | null;
+    memoryIds: string[] | null;
+    similarityScores: number[] | null;
+    metadata: Record<string, unknown> | null;
+    embeddingProvider: string | null;
+    model: string | null;
+    error: string | null;
+    errorStack: string | null;
+    parentTraceId: string | null;
+    organization: string | null;
+    agentId: string | null;
+    tags: string[] | null;
+    checkpointId: string | null;
+    userMetadata: Record<string, unknown> | null;
+    extra: Record<string, unknown> | null;
+    latency: LatencyBreakdown | null;
+    explain: PersistedRecallExplainPayload | null;
+    spans: StageSpan[] | null;
+}
+interface TelemetryQuery {
+    operation?: TelemetryOperation | TelemetryOperation[];
+    status?: TelemetryStatus;
+    traceId?: string;
+    sessionId?: string;
+    organization?: string;
+    agentId?: string;
+    tag?: string;
+    checkpointId?: string;
+    memoryId?: string;
+    queryText?: string;
+    since?: string;
+    until?: string;
+    limit?: number;
+    offset?: number;
+    sortBy?: "timestamp" | "duration_ms";
+    sortDir?: "asc" | "desc";
+}
+interface TelemetryQueryResult {
+    events: TelemetryEvent[];
+    total: number;
+    limit: number;
+    offset: number;
+}
+/** Database config for the independent telemetry EventDatabase. */
+interface TelemetryDatabaseConfig {
+    provider: "sqlite" | "postgres";
+    /** Preferred v0.3 field. */
+    url?: string;
+    /** Back-compat alias for url. */
+    connectionString?: string;
+}
+interface TelemetryConfig {
+    enabled?: boolean;
+    database: TelemetryDatabaseConfig;
+    level?: TelemetryLogLevel;
+    captureQueries?: boolean;
+    captureLatency?: boolean;
+    captureErrors?: boolean;
+    captureSimilarity?: boolean;
+    captureEmbeddings?: boolean;
+}
+
+/**
+ * Public configuration and domain types for Wolbarg v0.3.
  */
 
 /** Opaque, user-defined metadata. Never validated or modified by the SDK. */
@@ -63,14 +211,19 @@ interface SqliteDatabaseConfig {
     /**
      * Path to the SQLite database file, or `:memory:` for an in-memory database.
      * Relative paths are resolved from `process.cwd()`.
+     * Prefer `url` in v0.3; `connectionString` remains supported.
      */
-    connectionString: string;
+    connectionString?: string;
+    /** v0.3 preferred alias for the SQLite path / connection. */
+    url?: string;
 }
 /** PostgreSQL database configuration. */
 interface PostgresDatabaseConfig {
     provider: "postgres";
     /** Postgres connection string (e.g. `postgres://user:pass@host:5432/db`). */
-    connectionString: string;
+    connectionString?: string;
+    /** v0.3 preferred alias for the Postgres connection string. */
+    url?: string;
     /** Optional max pool size. Defaults to 10. */
     maxPoolSize?: number;
 }
@@ -78,6 +231,7 @@ interface PostgresDatabaseConfig {
 type DatabaseConfig = SqliteDatabaseConfig | PostgresDatabaseConfig;
 /** Alias used by the constructor-based API. */
 type StorageConfig = DatabaseConfig;
+
 /**
  * OpenAI-compatible embedding endpoint configuration.
  * Works with OpenAI, Ollama, LM Studio, OpenRouter, Azure OpenAI, Gemini, etc.
@@ -194,6 +348,10 @@ interface RecallOptions {
      * Falls back to semantic-only when keyword search is not configured.
      */
     hybrid?: boolean | HybridConfig;
+    /**
+     * When `true`, return enriched explain results instead of plain RecallResult[].
+     */
+    explain?: boolean;
 }
 /** A single recalled memory with similarity score. */
 interface RecallResult {
@@ -207,6 +365,53 @@ interface RecallResult {
     createdAt: Date;
     updatedAt: Date;
 }
+/** Enriched recall hit when `explain: true`. */
+interface RecallExplanationHit {
+    memory: RecallResult;
+    score: number;
+    distance: number;
+    rankingReason: string;
+    matchedFields: string[];
+    metadataMatch: boolean;
+    providerUsed: string;
+    searchTime: number;
+    rankingTime: number;
+}
+/** Full explain-mode response. */
+interface RecallExplainResponse {
+    results: RecallExplanationHit[];
+    providerUsed: string;
+    searchTime: number;
+    rankingTime: number;
+    totalTime: number;
+    traceId: string;
+}
+/** Options for creating a named checkpoint. */
+interface CheckpointOptions {
+    description?: string;
+}
+/** Checkpoint metadata returned by checkpoint APIs. */
+interface CheckpointInfo {
+    name: string;
+    description: string | null;
+    createdAt: string;
+    sdkVersion: string;
+    provider: string;
+    snapshotPath: string;
+    sourcePath: string;
+    sizeBytes: number;
+}
+/** Result of export(). */
+interface ExportResult {
+    path: string;
+    sizeBytes: number;
+    exportedAt: string;
+}
+/** Result of import(). */
+interface ImportResult {
+    path: string;
+    importedAt: string;
+}
 /** Persisted memory record (without embedding vector). */
 interface MemoryRecord {
     id: string;
@@ -692,6 +897,67 @@ interface StorageProvider {
 /** Back-compat alias. */
 type DatabaseProvider = StorageProvider;
 
+/**
+ * Database-agnostic checkpoint contract.
+ * Snapshots memory state so callers can rollback without third-party libs.
+ */
+interface CheckpointMeta {
+    name: string;
+    description: string | null;
+    createdAt: string;
+    sdkVersion: string;
+    provider: string;
+    /** Absolute path or URI of the snapshot artifact. */
+    snapshotPath: string;
+    /** Absolute path or URI of the source memory database at creation time. */
+    sourcePath: string;
+    sizeBytes: number;
+}
+interface CreateCheckpointOptions {
+    description?: string;
+}
+interface CheckpointProvider {
+    readonly name: string;
+    /** Prepare checkpoint storage (directories / tables). */
+    open(): Promise<void>;
+    close(): Promise<void>;
+    /**
+     * Create a named snapshot of the current memory database.
+     * Must fail if the name already exists (never overwrite).
+     */
+    checkpoint(name: string, sourcePath: string, options?: CreateCheckpointOptions): Promise<CheckpointMeta>;
+    /** Restore the memory database from a named checkpoint. */
+    rollback(name: string, targetPath: string): Promise<CheckpointMeta>;
+    /** Permanently remove a checkpoint and its snapshot files. */
+    deleteCheckpoint(name: string): Promise<boolean>;
+    listCheckpoints(): Promise<CheckpointMeta[]>;
+    getCheckpoint(name: string): Promise<CheckpointMeta | null>;
+}
+
+/**
+ * Database-agnostic telemetry persistence contract.
+ * Telemetry MUST use a separate database from memory storage.
+ */
+
+interface TelemetryProvider {
+    readonly name: string;
+    /** Open the independent event database connection. */
+    open(): Promise<void>;
+    /** Close the event database connection. Flush pending writes first. */
+    close(): Promise<void>;
+    /**
+     * Persist a telemetry event. Must not block callers of memory operations.
+     * Implementations may queue and flush asynchronously.
+     */
+    emit(event: TelemetryEventInput): void;
+    /** Wait until the write queue is empty (used by tests / shutdown). */
+    flush(): Promise<void>;
+    /** Read events (primarily for Studio / debugging). Optional for write-only backends. */
+    query?(options: TelemetryQuery): Promise<TelemetryQueryResult>;
+    /** Fetch a single event by id. */
+    getEvent?(id: string): Promise<TelemetryEvent | null>;
+}
+
 /**
  * Optional vision provider — captions / descriptions / entities from images.
  */
@@ -718,19 +984,32 @@ declare function openaiVision(options: {
 }): VisionProvider;
 
 /**
- * Constructor options for Wolbarg v0.2.
+ * Constructor options for Wolbarg v0.3.
  */
 
 type EmbeddingInput = EmbeddingProvider | EmbeddingConfig;
 type LlmInput = LlmProvider | LlmConfig;
-type StorageInput = StorageProvider | StorageConfig;
+type StorageInput = StorageProvider | StorageConfig | DatabaseConfig;
 interface WolbargOptionsBase {
     /** Organization namespace isolating memories within a shared database. */
     organization: string;
-    /** Storage provider instance or config. */
-    storage: StorageInput;
+    /**
+     * Storage provider instance or config.
+     * Prefer `database` in v0.3 docs; `storage` remains fully supported.
+     */
+    storage?: StorageInput;
+    /**
+     * v0.3 alias for `storage`. Accepts `{ provider, url }` or `{ provider, connectionString }`.
+     */
+    database?: StorageInput;
     /** Embedding provider instance or config. */
     embedding: EmbeddingInput;
+    /** Optional independent telemetry system (separate database). */
+    telemetry?: TelemetryConfig | TelemetryProvider;
+    /** Optional checkpoint provider override (defaults to SQLite when file-backed). */
+    checkpoint?: CheckpointProvider;
+    /** Optional directory for SQLite checkpoints. */
+    checkpointDirectory?: string;
     /** Optional reranker — skipped when absent. */
     reranker?: RerankerProvider;
     /** Optional keyword search — enables hybrid recall when present. */
@@ -756,23 +1035,24 @@ interface WolbargOptionsWithLlm extends WolbargOptionsBase {
 type WolbargOptions = WolbargOptionsWithoutLlm | WolbargOptionsWithLlm;
 
 /**
- * Wolbarg — modular semantic memory SDK for AI agents (v0.2).
+ * Wolbarg — modular semantic memory SDK for AI agents (v0.3).
  *
  * @example
  * ```ts
- * import { Wolbarg, sqlite, openaiEmbedding, openaiLlm } from "wolbarg";
+ * import { wolbarg, openaiEmbedding, openaiLlm } from "wolbarg";
  *
- * const ctx = new Wolbarg({
+ * const ctx = wolbarg({
  *   organization: "my-org",
- *   storage: sqlite("./memory.db"),
+ *   database: { provider: "sqlite", url: "./memory.db" },
  *   embedding: openaiEmbedding({
  *     apiKey: process.env.OPENAI_API_KEY!,
  *     model: "text-embedding-3-small",
  *   }),
- *   llm: openaiLlm({
- *     apiKey: process.env.OPENAI_API_KEY!,
- *     model: "gpt-4.1-mini",
- *   }),
+ *   telemetry: {
+ *     enabled: true,
+ *     database: { provider: "sqlite", url: "./telemetry.db" },
+ *     level: "debug",
+ *   },
  * });
  *
  * await ctx.ready();
@@ -782,7 +1062,6 @@ type WolbargOptions = WolbargOptionsWithoutLlm | WolbargOptionsWithLlm;
  */
 
 declare class Wolbarg<HasLlm extends boolean = false> {
-    /** Compile-time capability flag — `true` when constructed with `llm`. */
     readonly __hasLlm: HasLlm;
     private initialized;
     private booting;
@@ -799,106 +1078,151 @@ declare class Wolbarg<HasLlm extends boolean = false> {
     private retrievalConfig;
     private embeddingDimensions;
     private readonly writeMutex;
-    /**
-     * Create an Wolbarg instance.
-     * When options are provided, providers are wired immediately and
-     * storage opens lazily on the first API call (or {@link ready}).
-     *
-     * Pass `llm` to enable {@link compress} (typed at compile time).
-     */
+    private telemetry;
+    private checkpointProvider;
+    private memoryDbPath;
+    private readonly transfer;
     constructor(options: WolbargOptionsWithLlm);
     constructor(options: WolbargOptionsWithoutLlm);
     constructor();
     /**
      * Backwards-compatible initialization (v0.1 API).
-     * Prefer the constructor with `storage` / `embedding` / optional `llm`.
      */
     init(options: InitOptions): Promise<void>;
-    /** Ensure storage is open and embedding dimensions are known. */
+    /** Ensure storage (and optional telemetry) are open. */
     ready(): Promise<void>;
     private boot;
     /** Store a semantic memory for an agent. */
     remember(options: RememberOptions): Promise<MemoryRecord>;
+    /** Batch remember — one parent event + child traces per item. */
+    rememberBatch(items: RememberOptions[]): Promise<MemoryRecord[]>;
     /**
      * Semantic / hybrid search over stored memories.
-     * Optional keyword, metadata, MMR, and rerank stages degrade gracefully.
-     */
-    recall(options: RecallOptions): Promise<RecallResult[]>;
-    /**
-     * Compress related memories for an agent into a single summarized memory.
-     * Only available when `llm` (or `compression`) was configured at construction.
+     * Pass `{ explain: true }` for enriched ranking diagnostics.
      */
+    recall(options: RecallOptions & {
+        explain: true;
+    }): Promise<RecallExplainResponse>;
+    recall(options: RecallOptions & {
+        explain?: false;
+    }): Promise<RecallResult[]>;
+    recall(options: RecallOptions): Promise<RecallResult[] | RecallExplainResponse>;
+    /** Batch recall — parent event + child traces. */
+    recallBatch(queries: Array<Omit<RecallOptions, "explain">>): Promise<RecallResult[][]>;
     compress(this: Wolbarg<true>, options: CompressOptions): Promise<CompressResult>;
     /** @internal */
     private runCompress;
-    /** Ingest a document: parse → OCR/vision (optional) → chunk → embed → store. */
     ingest(options: IngestOptions): Promise<IngestResult>;
-    /** Delete memories by ID or filter. */
     forget(options: ForgetOptions): Promise<number>;
-    /** Return the history of a memory. */
     history(options: HistoryOptions): Promise<HistoryResult>;
-    /** Aggregate statistics for the current organization. */
     stats(): Promise<StatsResult>;
-    /** Delete every memory in the current organization. */
     clear(options: ClearOptions): Promise<number>;
-    /**
-     * Serialize writes for SQLite (single connection). Postgres uses a pool and
-     * per-statement atomic CTEs — locking here only serializes throughput.
-     */
+    /** Create an immutable named checkpoint of the memory database. */
+    checkpoint(name: string, options?: CheckpointOptions): Promise<CheckpointInfo>;
+    /** Restore the memory database from a named checkpoint. */
+    rollback(name: string): Promise<CheckpointInfo>;
+    deleteCheckpoint(name: string): Promise<boolean>;
+    listCheckpoints(): Promise<CheckpointInfo[]>;
+    getCheckpoint(name: string): Promise<CheckpointInfo | null>;
+    /** Export the memory database to a portable SQLite + manifest bundle. */
+    export(exportPath: string): Promise<ExportResult>;
+    /** Import a previously exported memory database, replacing the current file. */
+    import(exportPath: string): Promise<ImportResult>;
+    /** Flush pending telemetry (useful in tests). */
+    flushTelemetry(): Promise<void>;
+    /** Session id for this SDK instance (telemetry traces). */
+    get sessionId(): string;
     private withWriteLock;
-    /** Close the database connection and release resources. */
     close(): Promise<void>;
-    /** Whether providers are ready for API calls. */
     get isInitialized(): boolean;
     private requireReady;
     private assertEmbeddingDimensions;
+    private requireCheckpointProvider;
+    private requireMemoryDbPath;
 }
+/** Preferred v0.3 entry — re-exported from factories as well. */
+declare function wolbarg$1(options: WolbargOptions): Wolbarg;
 
 /**
- * Custom error hierarchy for Wolbarg.
- * Raw SQLite / network errors are never exposed to consumers.
+ * Operation-scoped errors with reason + suggestion for developer experience.
  */
 /** Base class for all Wolbarg errors. */
 declare class WolbargError extends Error {
     readonly code: string;
-    constructor(message: string, code: string, options?: ErrorOptions);
+    readonly reason?: string;
+    readonly suggestion?: string;
+    readonly operation?: string;
+    constructor(message: string, code: string, options?: ErrorOptions & {
+        reason?: string;
+        suggestion?: string;
+        operation?: string;
+    });
 }
 /** Thrown when SDK initialization fails. */
 declare class InitializationError extends WolbargError {
-    constructor(message: string, options?: ErrorOptions);
+    constructor(message: string, options?: ErrorOptions & {
+        reason?: string;
+        suggestion?: string;
+        operation?: string;
+    });
 }
 /** Thrown when configuration values are missing or invalid. */
 declare class ConfigurationError extends WolbargError {
-    constructor(message: string, options?: ErrorOptions);
+    constructor(message: string, options?: ErrorOptions & {
+        reason?: string;
+        suggestion?: string;
+        operation?: string;
+    });
 }
 /** Thrown when method arguments fail validation. */
 declare class ValidationError extends WolbargError {
-    constructor(message: string, options?: ErrorOptions);
+    constructor(message: string, options?: ErrorOptions & {
+        reason?: string;
+        suggestion?: string;
+        operation?: string;
+    });
 }
 /** Thrown when a database operation fails. */
 declare class DatabaseError extends WolbargError {
-    constructor(message: string, options?: ErrorOptions);
+    constructor(message: string, options?: ErrorOptions & {
+        reason?: string;
+        suggestion?: string;
+        operation?: string;
+    });
 }
 /** Thrown when an embedding request fails. */
 declare class EmbeddingError extends WolbargError {
-    constructor(message: string, options?: ErrorOptions);
+    constructor(message: string, options?: ErrorOptions & {
+        reason?: string;
+        suggestion?: string;
+        operation?: string;
+    });
 }
 /** Thrown when compression (LLM summarization) fails. */
 declare class CompressionError extends WolbargError {
-    constructor(message: string, options?: ErrorOptions);
+    constructor(message: string, options?: ErrorOptions & {
+        reason?: string;
+        suggestion?: string;
+        operation?: string;
+    });
 }
 /** Thrown when a requested memory does not exist. */
 declare class MemoryNotFoundError extends WolbargError {
-    constructor(message: string, options?: ErrorOptions);
+    constructor(message: string, options?: ErrorOptions & {
+        reason?: string;
+        suggestion?: string;
+        operation?: string;
+    });
 }
 /**
  * Thrown when a method requires an optional provider that was not configured.
- * Prefer TypeScript narrowing (e.g. compress without llm) when possible.
  */
 declare class ProviderNotConfiguredError extends ConfigurationError {
     readonly provider: string;
     constructor(provider: string, method: string, hint: string);
 }
+/** Map low-level SQLite / driver errors into actionable operation errors. */
+declare function wrapOperationError(operation: string, error: unknown): WolbargError;
 
 /**
  * Public factory helpers for storage / providers.
@@ -917,6 +1241,16 @@ declare function postgres(options: string | {
 declare function postgresConfig(connectionString: string, options?: {
     maxPoolSize?: number;
 }): PostgresDatabaseConfig;
+/** Create a SQLite telemetry provider for an independent event database. */
+declare function sqliteTelemetry(url: string): TelemetryProvider;
+/** Create a SQLite checkpoint provider. */
+declare function sqliteCheckpoint(directory?: string): CheckpointProvider;
+/** Create a telemetry provider from config (SQLite only in v0.3). */
+declare function createTelemetryProvider(config: TelemetryConfig): TelemetryProvider;
+/**
+ * Preferred v0.3 factory. Equivalent to `new Wolbarg(options)`.
+ */
+declare function wolbarg(options: WolbargOptions): Wolbarg;
 
 /**
  * SQLite + sqlite-vec database provider (Node.js built-in `node:sqlite`).
@@ -947,6 +1281,8 @@ declare class SqliteStorageProvider implements StorageProvider {
     /** Resolved absolute path (or `:memory:`) — avoid re-resolving on size checks. */
     private resolvedPath;
     constructor(options: SqliteProviderOptions);
+    /** Absolute or relative path / `:memory:` used by this provider. */
+    get path(): string;
     open(): Promise<void>;
     close(): Promise<void>;
     ensureVectorSchema(dimensions: number): Promise<void>;
@@ -1146,4 +1482,212 @@ declare function createStorageProvider(config: StorageConfig | DatabaseConfig):
 /** @deprecated Prefer {@link createStorageProvider}. */
 declare function createDatabaseProvider(config: DatabaseConfig): StorageProvider;
 
-export { type ChatMessage, type Chunk, type ChunkingOptions, type ChunkingStrategy, type ClearOptions, type CompressOptions, type CompressResult, CompressionError, type CompressionProvider, ConfigurationError, type DatabaseConfig, DatabaseError, type DatabaseProvider, type DatabaseProviderName, type EmbeddingConfig, EmbeddingError, type EmbeddingProvider, FixedChunkingStrategy, type ForgetByFilterOptions, type ForgetByIdOptions, type ForgetOptions, HeadingChunkingStrategy, type HistoryEvent, type HistoryOptions, type HistoryResult, type HybridConfig, type IngestOptions, type IngestResult, type InitOptions, InitializationError, type KeywordDocument, type KeywordSearchHit, type KeywordSearchProvider, LlmCompressionProvider, type LlmConfig, type LlmProvider, MarkdownChunkingStrategy, type MemoryContent, type MemoryFilter, type MemoryMetadata, MemoryNotFoundError, type MemoryRecord, type MetadataFilter as MetaFilter, type MetadataComparison, type MetadataFilter, type MmrConfig, type OCRProvider, type OcrResult, ParagraphChunkingStrategy, type PostgresDatabaseConfig, PostgresStorageProvider, ProviderNotConfiguredError, type RecallOptions, type RecallResult, type RememberOptions, type RerankDocument, type RerankHit, type RerankerProvider, type RetrievalConfig, SentenceChunkingStrategy, type SqliteDatabaseConfig, SqliteDatabaseProvider, SqliteStorageProvider, type StatsResult, type StorageConfig, type StorageProvider, type StorageProviderName, ValidationError, type VisionProvider, type VisionResult, Wolbarg, WolbargError, type WolbargOptions, type WolbargOptionsWithLlm, type WolbargOptionsWithoutLlm, bgeReranker, bm25, cohereReranker, createChunkingStrategy, createCompressionProvider, createDatabaseProvider, createEmbeddingProvider, createLlmProvider, createStorageProvider, crossEncoder, geminiEmbedding, geminiVision, jinaReranker, lmStudioEmbedding, meta, ollamaEmbedding, ollamaLlm, openRouterEmbedding, openRouterLlm, openaiCompatibleEmbedding, openaiCompatibleLlm, openaiEmbedding, openaiLlm, openaiReranker, openaiVision, postgres, postgresConfig, sqlite, sqliteConfig, tesseract, togetherEmbedding, vllmEmbedding };
+/**
+ * Database-agnostic memory persistence contract.
+ * Alias of StorageProvider for the v0.3 provider architecture.
+ */
+
+/** Memory / vector storage provider. Implementations: SQLite, PostgreSQL. */
+type MemoryProvider = StorageProvider;
+
+/**
+ * Internal event persistence contract.
+ * Distinct from MemoryDatabase / StorageProvider — telemetry never shares tables.
+ */
+
+interface EventDatabase {
+    readonly name: string;
+    open(): Promise<void>;
+    close(): Promise<void>;
+    /** Insert one event row. */
+    insertEvent(event: TelemetryEventInput): Promise<TelemetryEvent>;
+    /** Insert many events in one batch (optional optimization). */
+    insertEvents?(events: TelemetryEventInput[]): Promise<TelemetryEvent[]>;
+    query(options: TelemetryQuery): Promise<TelemetryQueryResult>;
+    getEvent(id: string): Promise<TelemetryEvent | null>;
+    /** Aggregate helpers used by Studio backends. */
+    countEvents?(filter?: {
+        since?: string;
+        operation?: string;
+    }): Promise<number>;
+}
+
+/**
+ * SQLite EventDatabase — completely separate from the memory database.
+ */
+
+interface SqliteEventDatabaseOptions {
+    url: string;
+    /** When true, open read-only (Studio). */
+    readonly?: boolean;
+}
+declare class SqliteEventDatabase implements EventDatabase {
+    readonly name = "sqlite";
+    private readonly url;
+    private readonly readonly;
+    private db;
+    private insertStmt;
+    private columns;
+    constructor(options: SqliteEventDatabaseOptions);
+    open(): Promise<void>;
+    close(): Promise<void>;
+    insertEvent(input: TelemetryEventInput): Promise<TelemetryEvent>;
+    insertEvents(inputs: TelemetryEventInput[]): Promise<TelemetryEvent[]>;
+    query(options: TelemetryQuery): Promise<TelemetryQueryResult>;
+    getEvent(id: string): Promise<TelemetryEvent | null>;
+    countEvents(filter?: {
+        since?: string;
+        operation?: string;
+    }): Promise<number>;
+    private requireDb;
+    private migrateToV2;
+    private addOptionalColumnFilter;
+    private resolvePath;
+}
+
+/**
+ * SQLite TelemetryProvider backed by an independent EventDatabase.
+ * Writes are queued and flushed asynchronously so memory ops stay fast.
+ */
+
+interface SqliteTelemetryProviderOptions {
+    url: string;
+}
+declare class SqliteTelemetryProvider implements TelemetryProvider {
+    readonly name = "sqlite";
+    private readonly db;
+    private queue;
+    private flushing;
+    private closed;
+    private openPromise;
+    constructor(options: SqliteTelemetryProviderOptions);
+    open(): Promise<void>;
+    close(): Promise<void>;
+    emit(event: TelemetryEventInput): void;
+    flush(): Promise<void>;
+    query(options: TelemetryQuery): Promise<TelemetryQueryResult>;
+    getEvent(id: string): Promise<TelemetryEvent | null>;
+    private scheduleFlush;
+    private runFlush;
+}
+
+/**
+ * First-party SQLite checkpoint provider.
+ * Creates immutable named snapshots of the memory database.
+ */
+
+interface SqliteCheckpointProviderOptions {
+    /** Directory that stores checkpoint snapshots + metadata. */
+    directory?: string;
+}
+declare class SqliteCheckpointProvider implements CheckpointProvider {
+    readonly name = "sqlite";
+    private readonly directory;
+    private ready;
+    constructor(options?: SqliteCheckpointProviderOptions);
+    open(): Promise<void>;
+    close(): Promise<void>;
+    checkpoint(name: string, sourcePath: string, options?: CreateCheckpointOptions): Promise<CheckpointMeta>;
+    rollback(name: string, targetPath: string): Promise<CheckpointMeta>;
+    deleteCheckpoint(name: string): Promise<boolean>;
+    listCheckpoints(): Promise<CheckpointMeta[]>;
+    getCheckpoint(name: string): Promise<CheckpointMeta | null>;
+    private metaPath;
+    private snapshotPath;
+    private requireReady;
+}
+
+/**
+ * Cross-platform structured logger gated by TelemetryLogLevel.
+ */
+
+declare class WolbargLogger {
+    private level;
+    constructor(level?: TelemetryLogLevel);
+    setLevel(level: TelemetryLogLevel): void;
+    getLevel(): TelemetryLogLevel;
+    error(message: string, extra?: unknown): void;
+    warn(message: string, extra?: unknown): void;
+    info(message: string, extra?: unknown): void;
+    debug(message: string, extra?: unknown): void;
+    trace(message: string, extra?: unknown): void;
+    private write;
+}
+
+/**
+ * Trace context helpers — session_id, trace_id, parent_trace_id.
+ */
+interface TraceContext {
+    sessionId: string;
+    traceId: string;
+    parentTraceId: string | null;
+}
+
+/**
+ * Async telemetry emitter that never blocks memory operations.
+ */
+
+declare class NoopTelemetryProvider implements TelemetryProvider {
+    readonly name = "noop";
+    open(): Promise<void>;
+    close(): Promise<void>;
+    emit(_event: TelemetryEventInput): void;
+    flush(): Promise<void>;
+}
+interface OperationTraceHandle {
+    context: TraceContext;
+    startedAt: number;
+    latency: Partial<LatencyBreakdown>;
+    child(operation: TelemetryOperation): OperationTraceHandle;
+    mark(stage: keyof Omit<LatencyBreakdown, "totalMs">, ms: number): void;
+    success(fields?: Partial<TelemetryEventInput>): void;
+    failure(error: unknown, fields?: Partial<TelemetryEventInput>): void;
+}
+interface TelemetryEmitterContext {
+    organization?: string | null;
+}
+declare class TelemetryEmitter {
+    readonly sessionId: string;
+    readonly logger: WolbargLogger;
+    private provider;
+    private readonly config;
+    private readonly context;
+    constructor(provider: TelemetryProvider | null, config?: Partial<TelemetryConfig>, context?: TelemetryEmitterContext);
+    get enabled(): boolean;
+    setProvider(provider: TelemetryProvider): void;
+    open(): Promise<void>;
+    close(): Promise<void>;
+    flush(): Promise<void>;
+    start(operation: TelemetryOperation, parent?: TraceContext): OperationTraceHandle;
+    emitStartup(provider: string): void;
+    emitShutdown(provider: string): void;
+}
+
+/**
+ * Internal benchmark helpers for CLI / Studio later.
+ * @internal
+ */
+interface BenchmarkSample {
+    name: string;
+    durationMs: number;
+    ok: boolean;
+    error?: string;
+}
+interface BenchmarkReport {
+    startedAt: string;
+    finishedAt: string;
+    samples: BenchmarkSample[];
+    summary: {
+        count: number;
+        ok: number;
+        failed: number;
+        avgMs: number;
+        p50Ms: number;
+        p95Ms: number;
+        p99Ms: number;
+    };
+}
+declare function runBenchmark(name: string, iterations: number, fn: () => Promise<void> | void): Promise<BenchmarkSample[]>;
+declare function summarizeBenchmark(samples: BenchmarkSample[], startedAt: string, finishedAt: string): BenchmarkReport;
+
+export { type BenchmarkReport, type BenchmarkSample, type ChatMessage, type CheckpointInfo, type CheckpointMeta, type CheckpointOptions, type CheckpointProvider, type Chunk, type ChunkingOptions, type ChunkingStrategy, type ClearOptions, type CompressOptions, type CompressResult, CompressionError, type CompressionProvider, ConfigurationError, type CreateCheckpointOptions, type DatabaseConfig, DatabaseError, type DatabaseProvider, type DatabaseProviderName, type EmbeddingConfig, EmbeddingError, type EmbeddingProvider, type EventDatabase, type ExportResult, FixedChunkingStrategy, type ForgetByFilterOptions, type ForgetByIdOptions, type ForgetOptions, HeadingChunkingStrategy, type HistoryEvent, type HistoryOptions, type HistoryResult, type HybridConfig, type ImportResult, type IngestOptions, type IngestResult, type InitOptions, InitializationError, type KeywordDocument, type KeywordSearchHit, type KeywordSearchProvider, type LatencyBreakdown, LlmCompressionProvider, type LlmConfig, type LlmProvider, MarkdownChunkingStrategy, type MemoryContent, type MemoryFilter, type MemoryMetadata, MemoryNotFoundError, type MemoryProvider, type MemoryRecord, type MetadataFilter as MetaFilter, type MetadataComparison, type MetadataFilter, type MmrConfig, NoopTelemetryProvider, type OCRProvider, type OcrResult, ParagraphChunkingStrategy, type PersistedRecallExplainPayload, type PostgresDatabaseConfig, PostgresStorageProvider, ProviderNotConfiguredError, type RecallExplainResponse, type RecallExplanationHit, type RecallOptions, type RecallResult, type RememberOptions, type RerankDocument, type RerankHit, type RerankerProvider, type RetrievalConfig, SentenceChunkingStrategy, SqliteCheckpointProvider, type SqliteDatabaseConfig, SqliteDatabaseProvider, SqliteEventDatabase, SqliteStorageProvider, SqliteTelemetryProvider, type StageSpan, type StatsResult, type StorageConfig, type StorageProvider, type StorageProviderName, type TelemetryConfig, TelemetryEmitter, type TelemetryEvent, type TelemetryEventInput, type TelemetryLogLevel, type TelemetryOperation, type TelemetryProvider, type TelemetryQuery, type TelemetryQueryResult, type TelemetryStatus, ValidationError, type VisionProvider, type VisionResult, Wolbarg, WolbargError, WolbargLogger, type WolbargOptions, type WolbargOptionsWithLlm, type WolbargOptionsWithoutLlm, bgeReranker, bm25, cohereReranker, createChunkingStrategy, createCompressionProvider, createDatabaseProvider, createEmbeddingProvider, createLlmProvider, createStorageProvider, createTelemetryProvider, wolbarg as createWolbarg, crossEncoder, geminiEmbedding, geminiVision, jinaReranker, lmStudioEmbedding, meta, ollamaEmbedding, ollamaLlm, openRouterEmbedding, openRouterLlm, openaiCompatibleEmbedding, openaiCompatibleLlm, openaiEmbedding, openaiLlm, openaiReranker, openaiVision, postgres, postgresConfig, runBenchmark, sqlite, sqliteCheckpoint, sqliteConfig, sqliteTelemetry, summarizeBenchmark, tesseract, togetherEmbedding, vllmEmbedding, wolbarg$1 as wolbarg, wrapOperationError };