@mikesaintsg/core 0.0.1

package/dist/index.d.ts

@@ -0,0 +1,1299 @@
+/** Cancellable operation options */
+export declare interface AbortableOptions {
+    readonly signal?: AbortSignal;
+}
+
+/** Anthropic embedding adapter options */
+export declare interface AnthropicEmbeddingAdapterOptions {
+    readonly apiKey: string;
+    readonly model?: string;
+    readonly baseURL?: string;
+}
+
+/** Anthropic provider adapter options */
+export declare interface AnthropicProviderAdapterOptions {
+    readonly apiKey: string;
+    readonly model?: string;
+    readonly baseURL?: string;
+    readonly defaultOptions?: GenerationDefaults;
+}
+
+/** Anthropic tool schema format */
+export declare interface AnthropicTool {
+    readonly name: string;
+    readonly description: string;
+    readonly input_schema: unknown;
+}
+
+/** Anthropic tool format adapter options */
+export declare interface AnthropicToolFormatAdapterOptions {
+    readonly toolChoice?: 'auto' | 'any' | {
+        readonly name: string;
+    };
+}
+
+/** Anthropic tool use content block */
+export declare interface AnthropicToolUse {
+    readonly type: 'tool_use';
+    readonly id: string;
+    readonly name: string;
+    readonly input: Readonly<Record<string, unknown>>;
+}
+
+/** Batched embedding adapter interface - extends base with batching */
+export declare interface BatchedEmbeddingAdapterInterface extends EmbeddingAdapterInterface {
+    queue(text: string, options?: AbortableOptions): Promise<Embedding>;
+    queueBatch(texts: readonly string[], options?: AbortableOptions): Promise<readonly Embedding[]>;
+    flush(): Promise<void>;
+    getPendingCount(): number;
+    getCache(): EmbeddingCacheInterface | undefined;
+}
+
+/** Default timeout for bridge operations in milliseconds */
+export declare const BRIDGE_DEFAULT_TIMEOUT = 30000;
+
+/** Assembled context ready for inference */
+export declare interface BuiltContext {
+    readonly frames: readonly ContextFrame[];
+    readonly totalTokens: number;
+    readonly budget: TokenBudgetState;
+    readonly truncated: boolean;
+    readonly truncationInfo?: TruncationInfo;
+    readonly deduplication?: DeduplicationResult;
+    readonly timestamp: number;
+}
+
+/**
+ * Chain results (flatMap). Apply a function that returns a Result to a success value.
+ *
+ * @param result - The result to chain
+ * @param fn - Function returning a new Result
+ * @returns The result of applying fn, or the original error
+ *
+ * @example
+ * ```ts
+ * const parsed = chain(ok('42'), s => {
+ *   const n = parseInt(s, 10)
+ *   return isNaN(n) ? err('PARSE_ERROR') : ok(n)
+ * })
+ * // parsed = ok(42)
+ * ```
+ */
+export declare function chain<T, U, E>(result: Result<T, E>, fn: (value: T) => Result<U, E>): Result<U, E>;
+
+/** Origin of state change */
+export declare type ChangeSource = 'local' | 'remote';
+
+/**
+ * Compute a SHA-256 content hash for text.
+ *
+ * @param text - The text to hash
+ * @returns A hex string content hash
+ *
+ * @example
+ * ```ts
+ * const hash = await computeContentHash('Hello, world!')
+ * // hash = 'a591a6d40bf420404a011733cfb7b190d62c65bf0bcda32b57b277d9ad9f146e'
+ * ```
+ */
+export declare function computeContentHash(text: string): Promise<ContentHash>;
+
+/** Content hash for deduplication (SHA-256 hex string) */
+export declare type ContentHash = string;
+
+/** Context frame - atomic unit of context */
+export declare interface ContextFrame {
+    readonly id: string;
+    readonly type: FrameType;
+    readonly content: string;
+    readonly contentHash: ContentHash;
+    readonly priority: FramePriority;
+    readonly tokenEstimate: number;
+    readonly createdAt: number;
+    readonly metadata?: FrameMetadata;
+}
+
+/**
+ * Core package error.
+ *
+ * @example
+ * ```ts
+ * throw new CoreError('ADAPTER_ERROR', 'Failed to connect to OpenAI')
+ * ```
+ */
+export declare class CoreError extends Error {
+    readonly code: CoreErrorCode;
+    readonly cause: Error | undefined;
+    constructor(code: CoreErrorCode, message: string, cause?: Error);
+}
+
+/** Core package error codes */
+export declare type CoreErrorCode = 'ADAPTER_ERROR' | 'BRIDGE_ERROR' | 'VALIDATION_ERROR' | 'NOT_FOUND' | 'TIMEOUT' | 'ABORTED';
+
+/**
+ * Create an Anthropic-compatible embedding adapter.
+ *
+ * Note: Anthropic recommends Voyage AI for embeddings, so this adapter
+ * uses the Voyage AI API. The apiKey should be a Voyage AI API key.
+ *
+ * @param options - Adapter configuration
+ * @returns An embedding adapter for Anthropic/Voyage
+ *
+ * @example
+ * ```ts
+ * const adapter = createAnthropicEmbeddingAdapter({
+ *   apiKey: process.env.VOYAGE_API_KEY,
+ *   model: 'voyage-2',
+ * })
+ *
+ * const embeddings = await adapter.embed(['Hello, world!'])
+ * ```
+ */
+export declare function createAnthropicEmbeddingAdapter(options: AnthropicEmbeddingAdapterOptions): EmbeddingAdapterInterface;
+
+/**
+ * Create an Anthropic tool format adapter.
+ *
+ * @param options - Adapter options
+ * @returns A tool format adapter for Anthropic
+ *
+ * @example
+ * ```ts
+ * const adapter = createAnthropicToolFormatAdapter({
+ *   toolChoice: 'auto',
+ * })
+ *
+ * const formatted = adapter.formatSchemas(schemas)
+ * const calls = adapter.parseToolCalls(response)
+ * ```
+ */
+export declare function createAnthropicToolFormatAdapter(_options?: AnthropicToolFormatAdapterOptions): ToolFormatAdapterInterface;
+
+/**
+ * Create a batched embedding adapter that wraps any embedding adapter.
+ *
+ * @param adapter - The base embedding adapter to wrap
+ * @param options - Batching configuration options
+ * @returns A batched embedding adapter instance
+ *
+ * @example
+ * ```ts
+ * const baseAdapter = createOpenAIEmbeddingAdapter({ apiKey: '...' })
+ * const cache = createEmbeddingCache({ maxEntries: 1000 })
+ *
+ * const batched = createBatchedEmbeddingAdapter(baseAdapter, {
+ *   maxBatchSize: 100,
+ *   flushDelayMs: 50,
+ *   deduplicate: true,
+ *   cache,
+ * })
+ *
+ * // These will be batched together
+ * const [e1, e2] = await Promise.all([
+ *   batched.queue('text 1'),
+ *   batched.queue('text 2'),
+ * ])
+ * ```
+ */
+export declare function createBatchedEmbeddingAdapter(adapter: EmbeddingAdapterInterface, options?: EmbeddingBatchOptions): BatchedEmbeddingAdapterInterface;
+
+/** Factory function for creating embedding cache */
+export declare type CreateEmbeddingCache = (options?: EmbeddingCacheOptions) => EmbeddingCacheInterface;
+
+/**
+ * Create an in-memory embedding cache with LRU eviction.
+ *
+ * @param options - Cache configuration options
+ * @returns An embedding cache instance
+ *
+ * @example
+ * ```ts
+ * const cache = createEmbeddingCache({
+ *   maxEntries: 1000,
+ *   ttlMs: 60 * 60 * 1000, // 1 hour
+ * })
+ *
+ * cache.set('hash123', embedding)
+ * const cached = cache.get('hash123')
+ * ```
+ */
+export declare function createEmbeddingCache(options?: EmbeddingCacheOptions): EmbeddingCacheInterface;
+
+/**
+ * Create a navigation guard that prevents leaving when form is dirty.
+ *
+ * @param options - Form dirty guard configuration options
+ * @returns A navigation guard function
+ *
+ * @example
+ * ```ts
+ * import { createForm } from '@mikesaintsg/form'
+ * import { createFormDirtyGuard } from '@mikesaintsg/core'
+ *
+ * const form = createForm({ ... })
+ *
+ * const guard = createFormDirtyGuard({
+ *   form,
+ *   confirmFn: (message) => window.confirm(message),
+ *   message: 'You have unsaved changes. Continue?',
+ *   excludePages: ['settings'],
+ * })
+ *
+ * // Use with router
+ * router.beforeNavigate(guard)
+ * ```
+ */
+export declare function createFormDirtyGuard<TFormData = unknown, TPage extends string = string>(options: FormDirtyGuardOptions<TFormData, TPage>): NavigationGuard<TPage>;
+
+/**
+ * Create an HTTP persistence adapter for VectorStore.
+ *
+ * @param options - Adapter configuration
+ * @returns A persistence adapter using HTTP
+ *
+ * @example
+ * ```ts
+ * const adapter = createHTTPVectorStorePersistence({
+ *   baseURL: 'https://api.example.com/vectors',
+ *   headers: { 'Authorization': 'Bearer token' },
+ * })
+ *
+ * await adapter.save({ id: 'doc1', content: 'hello', embedding: new Float32Array([...]) })
+ * ```
+ */
+export declare function createHTTPVectorStorePersistence(options: HTTPPersistenceOptions): VectorStorePersistenceAdapterInterface;
+
+/**
+ * Create an IndexedDB persistence adapter for VectorStore.
+ *
+ * @param options - Adapter configuration
+ * @returns A persistence adapter using IndexedDB
+ *
+ * @example
+ * ```ts
+ * import { createDatabase } from '@mikesaintsg/indexeddb'
+ *
+ * const db = await createDatabase({ name: 'vectors' })
+ * const adapter = createIndexedDBVectorStorePersistence({
+ *   database: db,
+ *   documentsStore: 'embeddings',
+ * })
+ *
+ * await adapter.save({ id: 'doc1', content: 'hello', embedding: new Float32Array([...]) })
+ * ```
+ */
+export declare function createIndexedDBVectorStorePersistence(options: IndexedDBVectorStorePersistenceOptions): VectorStorePersistenceAdapterInterface;
+
+/**
+ * Create an OpenAI embedding adapter.
+ *
+ * @param options - OpenAI adapter configuration
+ * @returns An embedding adapter for OpenAI
+ *
+ * @example
+ * ```ts
+ * const adapter = createOpenAIEmbeddingAdapter({
+ *   apiKey: process.env.OPENAI_API_KEY,
+ *   model: 'text-embedding-3-small',
+ * })
+ *
+ * const embeddings = await adapter.embed(['Hello, world!'])
+ * ```
+ */
+export declare function createOpenAIEmbeddingAdapter(options: OpenAIEmbeddingAdapterOptions): EmbeddingAdapterInterface;
+
+/**
+ * Create an OpenAI tool format adapter.
+ *
+ * @param options - Adapter options
+ * @returns A tool format adapter for OpenAI
+ *
+ * @example
+ * ```ts
+ * const adapter = createOpenAIToolFormatAdapter({
+ *   toolChoice: 'auto',
+ * })
+ *
+ * const formatted = adapter.formatSchemas(schemas)
+ * const calls = adapter.parseToolCalls(response)
+ * ```
+ */
+export declare function createOpenAIToolFormatAdapter(_options?: OpenAIToolFormatAdapterOptions): ToolFormatAdapterInterface;
+
+/**
+ * Create an OPFS persistence adapter for VectorStore.
+ *
+ * @param options - Adapter configuration
+ * @returns A persistence adapter using OPFS
+ *
+ * @example
+ * ```ts
+ * import { createDirectory } from '@mikesaintsg/filesystem'
+ *
+ * const dir = await createDirectory({ name: 'vectors' })
+ * const adapter = createOPFSVectorStorePersistence({
+ *   directory: dir,
+ *   chunkSize: 50,
+ * })
+ *
+ * await adapter.save({ id: 'doc1', content: 'hello', embedding: new Float32Array([...]) })
+ * ```
+ */
+export declare function createOPFSVectorStorePersistence(options: OPFSVectorStorePersistenceOptions): VectorStorePersistenceAdapterInterface;
+
+/**
+ * Create a retrieval tool for use with contextprotocol tool registry.
+ *
+ * @param options - Retrieval tool configuration options
+ * @returns A tool schema and handler for registration
+ *
+ * @example
+ * ```ts
+ * import { createVectorStore } from '@mikesaintsg/vectorstore'
+ * import { createToolRegistry } from '@mikesaintsg/contextprotocol'
+ * import { createRetrievalTool } from '@mikesaintsg/core'
+ *
+ * const vectorStore = createVectorStore({ ... })
+ * const registry = createToolRegistry()
+ *
+ * const { schema, handler } = createRetrievalTool({
+ *   vectorStore,
+ *   name: 'search_docs',
+ *   description: 'Search documentation for relevant information',
+ *   defaultLimit: 5,
+ *   scoreThreshold: 0.7,
+ * })
+ *
+ * registry.register({ ...schema, execute: handler })
+ * ```
+ */
+export declare function createRetrievalTool<TMetadata = unknown>(options: RetrievalToolOptions<TMetadata>): RetrievalToolCreated;
+
+/**
+ * Create a session persistence adapter for storing inference sessions.
+ *
+ * @param options - Session persistence configuration options
+ * @returns A session persistence instance
+ *
+ * @example
+ * ```ts
+ * import { createDatabase } from '@mikesaintsg/indexeddb'
+ * import { createSessionPersistence } from '@mikesaintsg/core'
+ *
+ * const db = await createDatabase({ name: 'sessions' })
+ * const persistence = createSessionPersistence({
+ *   database: db,
+ *   storeName: 'chat_sessions',
+ *   autoprune: 7 * 24 * 60 * 60 * 1000, // 7 days
+ * })
+ *
+ * // Save session
+ * await persistence.save('session-1', session)
+ *
+ * // Load session
+ * const savedSession = await persistence.load('session-1')
+ * ```
+ */
+export declare function createSessionPersistence(options: SessionPersistenceOptions): SessionPersistenceInterface;
+
+/**
+ * Create a tool call bridge.
+ *
+ * @param options - Bridge configuration options
+ * @returns A tool call bridge instance
+ *
+ * @example
+ * ```ts
+ * import { createToolRegistry } from '@mikesaintsg/contextprotocol'
+ * import { createToolCallBridge } from '@mikesaintsg/core'
+ *
+ * const registry = createToolRegistry()
+ * registry.register(weatherTool)
+ *
+ * const bridge = createToolCallBridge({
+ *   registry,
+ *   timeout: 30000,
+ *   onError: (error, toolCall) => console.error(`Tool ${toolCall.name} failed:`, error),
+ * })
+ *
+ * // Execute tool calls from LLM response
+ * const results = await bridge.executeAll(response.toolCalls)
+ * ```
+ */
+export declare function createToolCallBridge(options: ToolCallBridgeOptions): ToolCallBridgeInterface;
+
+/** Deduplication result summary */
+export declare interface DeduplicationResult {
+    readonly originalCount: number;
+    readonly deduplicatedCount: number;
+    readonly removedFrames: readonly ContextFrame[];
+    readonly mergedFrames: readonly ContextFrame[];
+    readonly tokensSaved: number;
+}
+
+/**
+ * Deserialize a stored document from JSON storage.
+ * Converts array embeddings back to Float32Array.
+ *
+ * @param data - The plain object from JSON.parse
+ * @returns A StoredDocument with proper Float32Array embedding
+ *
+ * @example
+ * ```ts
+ * const data = JSON.parse(json)
+ * const doc = deserializeStoredDocument(data)
+ * ```
+ */
+export declare function deserializeStoredDocument(data: Record<string, unknown>): StoredDocument;
+
+/** Base ecosystem error */
+export declare abstract class EcosystemError extends Error {
+    abstract readonly code: string;
+    readonly cause: Error | undefined;
+}
+
+/** Embedding vector */
+export declare type Embedding = Float32Array;
+
+/** Default flush delay in milliseconds for batched embeddings */
+export declare const EMBEDDING_BATCH_DEFAULT_FLUSH_DELAY_MS = 50;
+
+/** Default maximum batch size for embedding requests */
+export declare const EMBEDDING_BATCH_DEFAULT_MAX_SIZE = 100;
+
+/** Default maximum entries for embedding cache */
+export declare const EMBEDDING_CACHE_DEFAULT_MAX_ENTRIES = 1000;
+
+/** Embedding generation contract */
+export declare interface EmbeddingAdapterInterface {
+    embed(texts: readonly string[], options?: AbortableOptions): Promise<readonly Embedding[]>;
+    getModelMetadata(): EmbeddingModelMetadata;
+}
+
+/** Embedding batch options */
+export declare interface EmbeddingBatchOptions {
+    readonly maxBatchSize?: number;
+    readonly flushDelayMs?: number;
+    readonly deduplicate?: boolean;
+    readonly cache?: EmbeddingCacheInterface;
+}
+
+/** Embedding cache entry */
+export declare interface EmbeddingCacheEntry {
+    readonly embedding: Embedding;
+    readonly contentHash: ContentHash;
+    readonly modelId: string;
+    readonly createdAt: number;
+    readonly hitCount: number;
+}
+
+/** Embedding cache interface */
+export declare interface EmbeddingCacheInterface {
+    get(contentHash: ContentHash): Embedding | undefined;
+    set(contentHash: ContentHash, embedding: Embedding): void;
+    has(contentHash: ContentHash): boolean;
+    remove(contentHash: ContentHash): boolean;
+    clear(): void;
+    getStats(): EmbeddingCacheStats;
+}
+
+/** LRU cache eviction options */
+export declare interface EmbeddingCacheOptions {
+    readonly maxEntries?: number;
+    readonly maxBytes?: number;
+    readonly ttlMs?: number;
+    readonly onEvict?: (contentHash: ContentHash, embedding: Embedding) => void;
+}
+
+/** Embedding cache statistics */
+export declare interface EmbeddingCacheStats {
+    readonly entries: number;
+    readonly hits: number;
+    readonly misses: number;
+    readonly hitRate: number;
+    readonly estimatedBytes: number;
+}
+
+/** Embedding model info */
+export declare interface EmbeddingModelMetadata {
+    readonly provider: string;
+    readonly model: string;
+    readonly dimensions: number;
+}
+
+/** Failure result */
+export declare interface Err<E> {
+    readonly ok: false;
+    readonly error: E;
+}
+
+/**
+ * Create a failure result.
+ *
+ * @param error - The error value
+ * @returns An Err result containing the error
+ *
+ * @example
+ * ```ts
+ * const result = err('NOT_FOUND')
+ * // result.ok === false
+ * // result.error === 'NOT_FOUND'
+ * ```
+ */
+export declare function err<E>(error: E): Err<E>;
+
+/** Extract error code type */
+export declare type ErrorCode<T extends EcosystemError> = T['code'];
+
+/**
+ * Estimate the byte size of an embedding.
+ *
+ * @param embedding - The embedding to measure
+ * @returns The byte length of the embedding
+ */
+export declare function estimateEmbeddingBytes(embedding: Embedding): number;
+
+/** Default form dirty guard message */
+export declare const FORM_DIRTY_DEFAULT_MESSAGE = "You have unsaved changes. Are you sure you want to leave?";
+
+/** Form dirty guard options */
+export declare interface FormDirtyGuardOptions<TFormData = unknown, TPage extends string = string> {
+    readonly form: FormMinimal<TFormData>;
+    readonly confirmFn: (message: string) => Promise<boolean> | boolean;
+    readonly message?: string;
+    readonly excludePages?: readonly TPage[];
+    readonly onlyFromPages?: readonly TPage[];
+}
+
+/**
+ * Minimal form interface for bridge functions.
+ * Avoids hard dependency on form packages.
+ */
+export declare interface FormMinimal<_TFormData = unknown> {
+    isDirty(): boolean;
+}
+
+/** Frame metadata */
+export declare interface FrameMetadata {
+    readonly sectionId?: string;
+    readonly filePath?: string;
+    readonly fileVersion?: number;
+    readonly toolName?: string;
+    readonly score?: number;
+    readonly tags?: readonly string[];
+    readonly expiresAt?: number;
+    readonly source?: string;
+}
+
+/** Frame priority levels */
+export declare type FramePriority = 'critical' | 'high' | 'normal' | 'low' | 'optional';
+
+/** Frame summary for reporting */
+export declare interface FrameSummary {
+    readonly id: string;
+    readonly type: FrameType;
+    readonly tokenEstimate: number;
+    readonly reason: TruncationReason;
+}
+
+/** Frame type discriminator */
+export declare type FrameType = 'system' | 'instruction' | 'section' | 'file' | 'document' | 'example' | 'tool' | 'memory' | 'retrieval' | 'custom';
+
+/** Generation defaults for provider adapters */
+export declare interface GenerationDefaults {
+    readonly temperature?: number;
+    readonly maxTokens?: number;
+    readonly topP?: number;
+    readonly stop?: readonly string[];
+}
+
+/** Default timeout for HTTP persistence requests in milliseconds */
+export declare const HTTP_DEFAULT_TIMEOUT = 30000;
+
+/** HTTP persistence options */
+export declare interface HTTPPersistenceOptions {
+    readonly baseURL: string;
+    readonly headers?: Readonly<Record<string, string>>;
+    readonly timeout?: number;
+}
+
+/** Default documents store name for IndexedDB persistence */
+export declare const INDEXEDDB_DEFAULT_DOCUMENTS_STORE = "documents";
+
+/** Default metadata store name for IndexedDB persistence */
+export declare const INDEXEDDB_DEFAULT_METADATA_STORE = "metadata";
+
+/** IndexedDB VectorStore persistence options */
+export declare interface IndexedDBVectorStorePersistenceOptions {
+    readonly database: MinimalDatabaseAccess;
+    readonly documentsStore?: string;
+    readonly metadataStore?: string;
+}
+
+/** In-memory embedding cache options */
+export declare interface InMemoryEmbeddingCacheOptions {
+    readonly maxEntries?: number;
+    readonly ttlMs?: number;
+}
+
+/**
+ * Type guard to check if an error is a CoreError.
+ *
+ * @param error - The value to check
+ * @returns True if the error is a CoreError
+ *
+ * @example
+ * ```ts
+ * try {
+ *   await adapter.embed(['text'])
+ * } catch (error) {
+ *   if (isCoreError(error)) {
+ *     console.log('Code:', error.code)
+ *   }
+ * }
+ * ```
+ */
+export declare function isCoreError(error: unknown): error is CoreError;
+
+/** Type guard for ecosystem errors */
+export declare function isEcosystemError(error: unknown): error is EcosystemError;
+
+/**
+ * Check if a result is a failure.
+ *
+ * @param result - The result to check
+ * @returns True if the result is Err, false otherwise
+ *
+ * @example
+ * ```ts
+ * const result: Result<number, string> = err('NOT_FOUND')
+ * if (isErr(result)) {
+ *   console.log(result.error) // TypeScript knows result is Err<string>
+ * }
+ * ```
+ */
+export declare function isErr<T, E>(result: Result<T, E>): result is Err<E>;
+
+/**
+ * Check if a result is a success.
+ *
+ * @param result - The result to check
+ * @returns True if the result is Ok, false otherwise
+ *
+ * @example
+ * ```ts
+ * const result: Result<number, string> = ok(42)
+ * if (isOk(result)) {
+ *   console.log(result.value) // TypeScript knows result is Ok<number>
+ * }
+ * ```
+ */
+export declare function isOk<T, E>(result: Result<T, E>): result is Ok<T>;
+
+/** JSON Schema 7 subset for tool parameters */
+export declare interface JSONSchema7 {
+    readonly type?: string | readonly string[];
+    readonly properties?: Readonly<Record<string, JSONSchema7>>;
+    readonly items?: JSONSchema7 | readonly JSONSchema7[];
+    readonly required?: readonly string[];
+    readonly enum?: readonly unknown[];
+    readonly const?: unknown;
+    readonly format?: string;
+    readonly minimum?: number;
+    readonly maximum?: number;
+    readonly minLength?: number;
+    readonly maxLength?: number;
+    readonly pattern?: string;
+    readonly description?: string;
+    readonly default?: unknown;
+    readonly additionalProperties?: boolean | JSONSchema7;
+    readonly anyOf?: readonly JSONSchema7[];
+    readonly oneOf?: readonly JSONSchema7[];
+    readonly allOf?: readonly JSONSchema7[];
+    readonly $ref?: string;
+    readonly definitions?: Readonly<Record<string, JSONSchema7>>;
+}
+
+/** Internal LRU cache entry with access tracking */
+export declare interface LRUCacheEntry {
+    readonly embedding: Embedding;
+    readonly createdAt: number;
+    hitCount: number;
+    lastAccess: number;
+}
+
+/**
+ * Map a function over a success value.
+ *
+ * @param result - The result to map over
+ * @param fn - Function to apply to the success value
+ * @returns A new result with the mapped value, or the original error
+ *
+ * @example
+ * ```ts
+ * const doubled = map(ok(5), x => x * 2) // ok(10)
+ * const failed = map(err('oops'), x => x * 2) // err('oops')
+ * ```
+ */
+export declare function map<T, U, E>(result: Result<T, E>, fn: (value: T) => U): Result<U, E>;
+
+/**
+ * Map a function over an error value.
+ *
+ * @param result - The result to map over
+ * @param fn - Function to apply to the error value
+ * @returns A new result with the mapped error, or the original value
+ *
+ * @example
+ * ```ts
+ * const wrapped = mapErr(err('oops'), e => new Error(e)) // err(Error('oops'))
+ * const unchanged = mapErr(ok(42), e => new Error(e)) // ok(42)
+ * ```
+ */
+export declare function mapErr<T, E, F>(result: Result<T, E>, fn: (error: E) => F): Result<T, F>;
+
+/**
+ * Minimal database access interface for cross-package adapters.
+ * Used by vectorstore persistence adapters to access IndexedDB without
+ * creating a hard dependency on the indexeddb package.
+ */
+export declare interface MinimalDatabaseAccess<T = unknown> {
+    store<S extends T>(name: string): MinimalStoreAccess<S>;
+}
+
+/**
+ * Minimal directory access interface for cross-package adapters.
+ * Used by vectorstore OPFS persistence adapters without creating
+ * a hard dependency on the filesystem package.
+ */
+export declare interface MinimalDirectoryAccess {
+    getFile(name: string): Promise<MinimalFileAccess | undefined>;
+    createFile(name: string): Promise<MinimalFileAccess>;
+    hasFile(name: string): Promise<boolean>;
+    removeFile(name: string): Promise<void>;
+    listFiles(): Promise<readonly MinimalFileAccess[]>;
+}
+
+/**
+ * Minimal file access interface for cross-package adapters.
+ */
+export declare interface MinimalFileAccess {
+    getName(): string;
+    getText(): Promise<string>;
+    getArrayBuffer(): Promise<ArrayBuffer>;
+    write(data: string | ArrayBuffer): Promise<void>;
+}
+
+/**
+ * Minimal store access interface for cross-package adapters.
+ * Provides only the operations needed by persistence adapters.
+ */
+export declare interface MinimalStoreAccess<T> {
+    get(key: IDBValidKey): Promise<T | undefined>;
+    set(value: T, key?: IDBValidKey): Promise<IDBValidKey>;
+    remove(key: IDBValidKey): Promise<void>;
+    all(): Promise<readonly T[]>;
+    clear(): Promise<void>;
+}
+
+/**
+ * Navigation guard function type.
+ * Returns true to allow navigation, false to block.
+ */
+export declare type NavigationGuard<TPage extends string = string> = (to: TPage, from: TPage) => Promise<boolean> | boolean;
+
+/** Success result */
+export declare interface Ok<T> {
+    readonly ok: true;
+    readonly value: T;
+}
+
+/**
+ * Create a success result.
+ *
+ * @param value - The success value
+ * @returns An Ok result containing the value
+ *
+ * @example
+ * ```ts
+ * const result = ok(42)
+ * // result.ok === true
+ * // result.value === 42
+ * ```
+ */
+export declare function ok<T>(value: T): Ok<T>;
+
+/** OpenAI API base URL */
+export declare const OPENAI_API_BASE_URL = "https://api.openai.com/v1";
+
+/** Default dimensions for OpenAI text-embedding-3-small */
+export declare const OPENAI_DEFAULT_EMBEDDING_DIMENSIONS = 1536;
+
+/** Default OpenAI embedding model */
+export declare const OPENAI_DEFAULT_EMBEDDING_MODEL = "text-embedding-3-small";
+
+/** OpenAI embedding adapter options */
+export declare interface OpenAIEmbeddingAdapterOptions {
+    readonly apiKey: string;
+    readonly model?: string;
+    readonly baseURL?: string;
+    readonly dimensions?: number;
+}
+
+/** OpenAI embedding data item */
+export declare interface OpenAIEmbeddingData {
+    readonly object: 'embedding';
+    readonly index: number;
+    readonly embedding: readonly number[];
+}
+
+/** OpenAI embedding API response */
+export declare interface OpenAIEmbeddingResponse {
+    readonly object: 'list';
+    readonly data: readonly OpenAIEmbeddingData[];
+    readonly model: string;
+    readonly usage: OpenAIEmbeddingUsage;
+}
+
+/** OpenAI embedding usage stats */
+export declare interface OpenAIEmbeddingUsage {
+    readonly prompt_tokens: number;
+    readonly total_tokens: number;
+}
+
+/** OpenAI provider adapter options */
+export declare interface OpenAIProviderAdapterOptions {
+    readonly apiKey: string;
+    readonly model?: string;
+    readonly baseURL?: string;
+    readonly organization?: string;
+    readonly defaultOptions?: GenerationDefaults;
+}
+
+/** OpenAI tool schema format */
+export declare interface OpenAITool {
+    readonly type: 'function';
+    readonly function: OpenAIToolFunction;
+}
+
+/** OpenAI tool call from response */
+export declare interface OpenAIToolCall {
+    readonly id: string;
+    readonly type: 'function';
+    readonly function: OpenAIToolCallFunction;
+}
+
+/** OpenAI tool call function */
+export declare interface OpenAIToolCallFunction {
+    readonly name: string;
+    readonly arguments: string;
+}
+
+/** OpenAI tool format adapter options */
+export declare interface OpenAIToolFormatAdapterOptions {
+    readonly toolChoice?: 'auto' | 'none' | 'required' | {
+        readonly name: string;
+    };
+}
+
+/** OpenAI tool function definition */
+export declare interface OpenAIToolFunction {
+    readonly name: string;
+    readonly description: string;
+    readonly parameters: unknown;
+}
+
+/** Default chunk size for OPFS persistence */
+export declare const OPFS_DEFAULT_CHUNK_SIZE = 100;
+
+/** Documents file name prefix for OPFS persistence */
+export declare const OPFS_DOCUMENTS_PREFIX = "chunk_";
+
+/** Metadata file name for OPFS persistence */
+export declare const OPFS_METADATA_FILE = "_metadata.json";
+
+/** OPFS VectorStore persistence options */
+export declare interface OPFSVectorStorePersistenceOptions {
+    readonly directory: MinimalDirectoryAccess;
+    readonly chunkSize?: number;
+}
+
+/**
+ * Generic error data interface for package-specific errors.
+ * Use this as a base for error data interfaces in packages.
+ *
+ * @example
+ * ```ts
+ * export type MyErrorCode = 'NOT_FOUND' | 'INVALID' | 'TIMEOUT'
+ * export interface MyErrorData extends PackageErrorData<MyErrorCode> {
+ *   readonly extra?: string
+ * }
+ * ```
+ */
+export declare interface PackageErrorData<TCode extends string> {
+    readonly code: TCode;
+    readonly cause?: Error;
+}
+
+/** Pending embedding request in batch queue */
+export declare interface PendingEmbeddingRequest {
+    readonly text: string;
+    readonly contentHash: ContentHash;
+    resolve: (embedding: Embedding) => void;
+    reject: (error: unknown) => void;
+}
+
+/**
+ * Provider adapter interface for LLM providers.
+ * Implemented by OpenAI, Anthropic, and other provider adapters.
+ */
+export declare interface ProviderAdapterInterface {
+    getId(): string;
+    supportsTools(): boolean;
+    supportsStreaming(): boolean;
+    getCapabilities(): ProviderCapabilities;
+}
+
+/** Provider capabilities information */
+export declare interface ProviderCapabilities {
+    readonly supportsTools: boolean;
+    readonly supportsStreaming: boolean;
+    readonly supportsVision: boolean;
+    readonly supportsFunctions: boolean;
+    readonly models: readonly string[];
+}
+
+/** Prune result information */
+export declare interface PruneResult {
+    readonly prunedCount: number;
+    readonly remainingCount: number;
+}
+
+/** Result union */
+export declare type Result<T, E> = Ok<T> | Err<E>;
+
+/** Default retrieval limit for retrieval tool */
+export declare const RETRIEVAL_DEFAULT_LIMIT = 10;
+
+/** Maximum retrieval limit for retrieval tool */
+export declare const RETRIEVAL_MAX_LIMIT = 100;
+
+/** Retrieval tool created by factory */
+export declare interface RetrievalToolCreated {
+    readonly schema: ToolSchema;
+    readonly handler: (args: Readonly<Record<string, unknown>>) => Promise<readonly unknown[]>;
+}
+
+/** Retrieval tool factory options */
+export declare interface RetrievalToolOptions<TMetadata = unknown> {
+    readonly vectorStore: VectorStoreMinimal<TMetadata>;
+    readonly name: string;
+    readonly description: string;
+    readonly defaultLimit?: number;
+    readonly maxLimit?: number;
+    readonly scoreThreshold?: number;
+    readonly formatResult?: (result: ScoredResult) => unknown;
+    readonly extendParameters?: Readonly<Record<string, JSONSchema7>>;
+    readonly buildFilter?: (params: Readonly<Record<string, unknown>>) => TMetadata | undefined;
+}
+
+/** Scored result from similarity search or retrieval */
+export declare interface ScoredResult {
+    readonly id: string;
+    readonly content: string;
+    readonly score: number;
+    readonly metadata?: Readonly<Record<string, unknown>>;
+    readonly embedding?: Embedding;
+}
+
+/**
+ * Minimal session interface for serialization.
+ * Avoids hard dependency on inference package.
+ */
+export declare interface SerializableSession {
+    getMessages(): readonly SerializedMessage[];
+    getMetadata(): SessionMetadata;
+}
+
+/** Serialized message for persistence */
+export declare interface SerializedMessage {
+    readonly role: 'user' | 'assistant' | 'system' | 'tool';
+    readonly content: string;
+    readonly toolCalls?: readonly ToolCall[];
+    readonly toolResult?: ToolResult;
+}
+
+/** Serialized session for storage */
+export declare interface SerializedSession {
+    readonly id: string;
+    readonly messages: readonly SerializedMessage[];
+    readonly metadata: SessionMetadata;
+    readonly updatedAt: number;
+}
+
+/**
+ * Serialize a stored document for JSON storage.
+ * Converts Float32Array embeddings to regular arrays.
+ *
+ * @param doc - The document to serialize
+ * @returns A plain object suitable for JSON.stringify
+ *
+ * @example
+ * ```ts
+ * const serialized = serializeStoredDocument(doc)
+ * const json = JSON.stringify(serialized)
+ * ```
+ */
+export declare function serializeStoredDocument(doc: StoredDocument): Record<string, unknown>;
+
+/** Session metadata for persistence */
+export declare interface SessionMetadata {
+    readonly model: string;
+    readonly provider: string;
+    readonly createdAt: number;
+    readonly system?: string;
+}
+
+/**
+ * Session persistence interface.
+ * Connects inference sessions to IndexedDB storage.
+ */
+export declare interface SessionPersistenceInterface {
+    save(id: string, session: SerializableSession): Promise<void>;
+    load(id: string): Promise<SerializedSession | undefined>;
+    delete(id: string): Promise<void>;
+    list(): Promise<readonly string[]>;
+    prune(maxAgeMs: number): Promise<number>;
+}
+
+/** Session persistence options */
+export declare interface SessionPersistenceOptions {
+    readonly database: MinimalDatabaseAccess;
+    readonly storeName: string;
+    readonly autoprune?: number;
+    readonly onSaveError?: (error: unknown, sessionId: string) => void;
+}
+
+/** Storage information (quota and usage) */
+export declare interface StorageInfo {
+    readonly usage: number;
+    readonly quota: number;
+    readonly available: number;
+    readonly percentUsed: number;
+}
+
+/** Stored document for persistence */
+export declare interface StoredDocument {
+    readonly id: string;
+    readonly content: string;
+    readonly embedding: Embedding;
+    readonly metadata?: Readonly<Record<string, unknown>>;
+    readonly contentHash?: ContentHash;
+    readonly createdAt?: number;
+    readonly updatedAt?: number;
+}
+
+/** Converts subscription methods to hook callbacks for options */
+export declare type SubscriptionToHook<T> = {
+    [K in keyof T]?: T[K] extends (callback: infer CB) => Unsubscribe ? CB : never;
+};
+
+/** Token budget level */
+export declare type TokenBudgetLevel = 'ok' | 'warning' | 'critical' | 'exceeded';
+
+/** Token budget state */
+export declare interface TokenBudgetState {
+    readonly used: number;
+    readonly available: number;
+    readonly reserved: number;
+    readonly max: number;
+    readonly usage: number;
+    readonly level: TokenBudgetLevel;
+}
+
+/** Tool call from LLM response */
+export declare interface ToolCall {
+    readonly id: string;
+    readonly name: string;
+    readonly arguments: Record<string, unknown>;
+}
+
+/**
+ * Tool call bridge interface.
+ * Connects inference tool calls to contextprotocol tool registry.
+ */
+export declare interface ToolCallBridgeInterface {
+    execute(toolCall: ToolCall): Promise<ToolResult>;
+    executeAll(toolCalls: readonly ToolCall[]): Promise<readonly ToolResult[]>;
+    hasTool(name: string): boolean;
+}
+
+/** Tool call bridge options */
+export declare interface ToolCallBridgeOptions {
+    readonly registry: ToolRegistryMinimal;
+    readonly timeout?: number;
+    readonly onError?: (error: unknown, toolCall: ToolCall) => void;
+    readonly onBeforeExecute?: (toolCall: ToolCall) => void;
+    readonly onAfterExecute?: (toolCall: ToolCall, result: unknown) => void;
+}
+
+/**
+ * Tool format adapter interface.
+ * Converts between internal tool representations and provider-specific formats.
+ */
+export declare interface ToolFormatAdapterInterface {
+    formatSchemas(schemas: readonly ToolSchema[]): unknown;
+    parseToolCalls(response: unknown): readonly ToolCall[];
+    formatResult(result: ToolResult): unknown;
+}
+
+/**
+ * Minimal tool registry interface for bridge functions.
+ * Avoids hard dependency on contextprotocol package.
+ */
+export declare interface ToolRegistryMinimal {
+    has(name: string): boolean;
+    execute(name: string, args: Readonly<Record<string, unknown>>): Promise<unknown>;
+}
+
+/** Tool execution result */
+export declare interface ToolResult {
+    readonly callId: string;
+    readonly name: string;
+    readonly success: boolean;
+    readonly value?: unknown;
+    readonly error?: string;
+}
+
+/** Tool schema definition */
+export declare interface ToolSchema {
+    readonly name: string;
+    readonly description: string;
+    readonly parameters: JSONSchema7;
+    readonly returns?: JSONSchema7;
+}
+
+/** Truncation information */
+export declare interface TruncationInfo {
+    readonly originalFrameCount: number;
+    readonly keptFrameCount: number;
+    readonly removedFrames: readonly FrameSummary[];
+    readonly strategy: TruncationStrategy;
+}
+
+/** Why a frame was truncated */
+export declare type TruncationReason = 'budget_exceeded' | 'priority_too_low' | 'expired' | 'deduplicated' | 'manual';
+
+/** Truncation strategy */
+export declare type TruncationStrategy = 'priority' | 'fifo' | 'lifo' | 'score' | 'custom';
+
+/**
+ * @mikesaintsg/core
+ *
+ * Type definitions for the core library.
+ * All public types and interfaces are defined here as the SOURCE OF TRUTH.
+ */
+/** Cleanup function returned by event subscriptions */
+export declare type Unsubscribe = () => void;
+
+/**
+ * Unwrap a result, returning the value or a default.
+ *
+ * @param result - The result to unwrap
+ * @param defaultValue - Value to return if result is an error
+ * @returns The success value or the default value
+ *
+ * @example
+ * ```ts
+ * const value = unwrap(ok(42), 0) // 42
+ * const fallback = unwrap(err('oops'), 0) // 0
+ * ```
+ */
+export declare function unwrap<T, E>(result: Result<T, E>, defaultValue: T): T;
+
+/**
+ * Unwrap a result, throwing if it's an error.
+ *
+ * @param result - The result to unwrap
+ * @returns The success value
+ * @throws The error if result is Err
+ *
+ * @example
+ * ```ts
+ * const value = unwrapOrThrow(ok(42)) // 42
+ * unwrapOrThrow(err(new Error('oops'))) // throws Error('oops')
+ * ```
+ */
+export declare function unwrapOrThrow<T, E>(result: Result<T, E>): T;
+
+/** Metadata key for VectorStore in persistence */
+export declare const VECTORSTORE_METADATA_KEY = "vectorstore_metadata";
+
+/** VectorStore metadata for persistence */
+export declare interface VectorStoreMetadata {
+    readonly dimensions: number;
+    readonly model: string;
+    readonly provider: string;
+    readonly documentCount: number;
+    readonly createdAt: number;
+    readonly updatedAt: number;
+}
+
+/**
+ * Minimal vectorstore interface for bridge functions.
+ * Avoids hard dependency on vectorstore package.
+ */
+export declare interface VectorStoreMinimal<TMetadata = unknown> {
+    search(query: string, options?: VectorStoreSearchOptions<TMetadata>): Promise<readonly ScoredResult[]>;
+}
+
+/**
+ * VectorStore persistence adapter interface.
+ * Implemented by IndexedDB, OPFS, and HTTP adapters.
+ */
+export declare interface VectorStorePersistenceAdapterInterface {
+    load(): Promise<readonly StoredDocument[]>;
+    loadMetadata(): Promise<VectorStoreMetadata | undefined>;
+    save(docs: StoredDocument | readonly StoredDocument[]): Promise<void>;
+    saveMetadata(metadata: VectorStoreMetadata): Promise<void>;
+    remove(ids: string | readonly string[]): Promise<void>;
+    clear(): Promise<void>;
+    isAvailable(): Promise<boolean>;
+}
+
+/** VectorStore search options */
+export declare interface VectorStoreSearchOptions<TMetadata = unknown> {
+    readonly limit?: number;
+    readonly filter?: TMetadata;
+}
+
+/** Voyage AI API base URL */
+export declare const VOYAGE_API_BASE_URL = "https://api.voyageai.com/v1";
+
+/** Default dimensions for Voyage AI voyage-2 */
+export declare const VOYAGE_DEFAULT_EMBEDDING_DIMENSIONS = 1024;
+
+/** Default Voyage AI embedding model (recommended by Anthropic) */
+export declare const VOYAGE_DEFAULT_EMBEDDING_MODEL = "voyage-2";
+
+/** Voyage AI embedding data item */
+export declare interface VoyageEmbeddingData {
+    readonly object: 'embedding';
+    readonly index: number;
+    readonly embedding: readonly number[];
+}
+
+/** Voyage AI embedding API response */
+export declare interface VoyageEmbeddingResponse {
+    readonly object: 'list';
+    readonly data: readonly VoyageEmbeddingData[];
+    readonly model: string;
+    readonly usage: VoyageEmbeddingUsage;
+}
+
+/** Voyage AI embedding usage stats */
+export declare interface VoyageEmbeddingUsage {
+    readonly total_tokens: number;
+}
+
+export { }