@mikesaintsg/core 0.0.2 → 0.0.4

package/dist/index.d.ts

@@ -3,13 +3,17 @@ export declare interface AbortableOptions {
     readonly signal?: AbortSignal;
 }
 
-/** 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;
+/**
+ * Batch adapter interface.
+ * Controls batching behavior for bulk operations.
+ */
+export declare interface BatchAdapterInterface {
+    /** Maximum items per batch */
+    getBatchSize(): number;
+    /** Delay between batches (ms) */
+    getDelayMs(): number;
+    /** Whether to deduplicate items within a batch */
+    shouldDeduplicate(): boolean;
 }
 
 /** Default timeout for bridge operations in milliseconds */
@@ -26,6 +30,14 @@ export declare interface BuiltContext {
     readonly timestamp: number;
 }
 
+/** Cache statistics */
+export declare interface CacheStats {
+    readonly hits: number;
+    readonly misses: number;
+    readonly size: number;
+    readonly maxSize?: number;
+}
+
 /**
  * Chain results (flatMap). Apply a function that returns a Result to a success value.
  *
@@ -76,26 +88,6 @@ export declare interface ContextFrame {
     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';
-
-/** Factory function for creating embedding cache */
-export declare type CreateEmbeddingCache = (options?: EmbeddingCacheOptions) => EmbeddingCacheInterface;
-
 /**
  * Create a navigation guard that prevents leaving when form is dirty.
  *
@@ -148,7 +140,7 @@ export declare function createFormDirtyGuard<TFormData = unknown, TPage extends
  * registry.register({ ...schema, execute: handler })
  * ```
  */
-export declare function createRetrievalTool<TMetadata = unknown>(options: RetrievalToolOptions<TMetadata>): RetrievalToolCreated;
+export declare function createRetrievalTool<TMetadata = unknown>(options: RetrievalToolOptions<TMetadata>): RetrievalToolInterface;
 
 /**
  * Create a session persistence adapter for storing inference sessions.
@@ -198,11 +190,23 @@ export declare function createSessionPersistence(options: SessionPersistenceOpti
  * })
  *
  * // Execute tool calls from LLM response
- * const results = await bridge.executeAll(response.toolCalls)
+ * const results = await bridge.execute(response.toolCalls)
  * ```
  */
 export declare function createToolCallBridge(options: ToolCallBridgeOptions): ToolCallBridgeInterface;
 
+/**
+ * Deduplication adapter interface.
+ * Determines how to handle duplicate frames based on content hash.
+ * Implemented in @mikesaintsg/adapters.
+ */
+export declare interface DeduplicationAdapterInterface {
+    /** Select which frame to keep from duplicates with the same content hash */
+    select(frames: readonly ContextFrame[]): ContextFrame;
+    /** Check if a frame should be preserved regardless of deduplication */
+    shouldPreserve(frame: ContextFrame): boolean;
+}
+
 /** Deduplication result summary */
 export declare interface DeduplicationResult {
     readonly originalCount: number;
@@ -212,73 +216,87 @@ export declare interface DeduplicationResult {
     readonly tokensSaved: number;
 }
 
+/** Deduplication strategy for default adapter */
+export declare type DeduplicationStrategy = 'keep_latest' | 'keep_first' | 'keep_highest_priority' | 'merge';
+
+/** Resource that must be explicitly destroyed */
+export declare interface Destroyable {
+    /** Release all resources held by this instance. After calling, the instance is unusable. */
+    destroy(): void;
+}
+
+/**
+ * @mikesaintsg/core
+ *
+ * Base error class and utilities for the ecosystem.
+ */
 /**
  * Base error class for all ecosystem errors.
  * All package-specific errors should extend this class.
+ *
+ * @example
+ * ```ts
+ * class StorageError extends EcosystemError {
+ *   readonly code: StorageErrorCode
+ *
+ *   constructor(code: StorageErrorCode, message: string, cause?: Error) {
+ *     super(message, cause)
+ *     this.code = code
+ *   }
+ * }
+ * ```
  */
 export declare abstract class EcosystemError extends Error {
+    /** Error code for programmatic handling */
     abstract readonly code: string;
+    /** Original error that caused this one */
     readonly cause: Error | undefined;
     constructor(message: string, cause?: Error);
 }
 
-/** Embedding vector */
+/** A single embedding vector. Float32Array for memory efficiency and typed array operations. */
 export declare type Embedding = Float32Array;
 
-/** Embedding generation contract */
+/**
+ * Contract for embedding generation.
+ * Implemented by adapters, consumed by vectorstore.
+ */
 export declare interface EmbeddingAdapterInterface {
+    /**
+     * Generate embeddings for one or more texts.
+     * @param texts - Texts to embed
+     * @param options - Optional abort signal
+     * @returns Embeddings in same order as input texts
+     */
     embed(texts: readonly string[], options?: AbortableOptions): Promise<readonly Embedding[]>;
+    /** Get metadata about the embedding model. Used for compatibility checking. */
     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;
+/**
+ * Embedding cache adapter interface.
+ * Provides caching for embedding operations.
+ */
+export declare interface EmbeddingCacheAdapterInterface {
+    /** Get cached embedding for text */
+    get(text: string): Embedding | undefined;
+    /** Store embedding in cache */
+    set(text: string, embedding: Embedding): void;
+    /** Check if text is cached */
+    has(text: string): boolean;
+    /** Clear all cached embeddings */
     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;
+    /** Optional: Get cache statistics */
+    getStats?(): CacheStats;
 }
 
-/** Embedding model info */
+/** Metadata identifying an embedding model. Used to ensure vector compatibility. */
 export declare interface EmbeddingModelMetadata {
+    /** Provider name (e.g., 'openai', 'anthropic') */
     readonly provider: string;
+    /** Model identifier (e.g., 'text-embedding-3-small') */
     readonly model: string;
+    /** Vector dimensions produced by this model */
     readonly dimensions: number;
 }
 
@@ -303,12 +321,26 @@ export declare interface Err<E> {
  */
 export declare function err<E>(error: E): Err<E>;
 
-/** Extract error code type */
-export declare type ErrorCode<T extends EcosystemError> = T['code'];
+/** Extract error code type from an error class */
+export declare type ErrorCode<T extends {
+    readonly code: string;
+}> = T['code'];
+
+/** Generation finish reason */
+export declare type FinishReason = 'stop' | 'length' | 'tool_calls' | 'content_filter' | 'error';
 
 /** Default form dirty guard message */
 export declare const FORM_DIRTY_DEFAULT_MESSAGE = "You have unsaved changes. Are you sure you want to leave?";
 
+/**
+ * Default result formatter for retrieval tools.
+ * Returns content, score, and metadata.
+ *
+ * @param result - Scored result to format
+ * @returns Formatted result object
+ */
+export declare function formatScoredResult(result: ScoredResult): unknown;
+
 /** Form dirty guard options */
 export declare interface FormDirtyGuardOptions<TFormData = unknown, TPage extends string = string> {
     readonly form: FormMinimal<TFormData>;
@@ -361,45 +393,29 @@ export declare interface GenerationDefaults {
     readonly stop?: readonly string[];
 }
 
-/** HTTP persistence options */
-export declare interface HTTPPersistenceOptions {
-    readonly baseURL: string;
-    readonly headers?: Readonly<Record<string, string>>;
-    readonly timeout?: number;
-}
-
-/** IndexedDB VectorStore persistence options */
-export declare interface IndexedDBVectorStorePersistenceOptions {
-    readonly database: MinimalDatabaseAccess;
-    readonly documentsStore?: string;
-    readonly metadataStore?: string;
+/** Generation options */
+export declare interface GenerationOptions extends AbortableOptions {
+    readonly model?: string;
+    readonly temperature?: number;
+    readonly maxTokens?: number;
+    readonly topP?: number;
+    readonly tools?: readonly ToolSchema[];
+    readonly toolChoice?: 'auto' | 'none' | 'required' | {
+        readonly name: string;
+    };
+    readonly stop?: readonly string[];
+    readonly timeout?: TimeoutOptions;
 }
 
-/** In-memory embedding cache options */
-export declare interface InMemoryEmbeddingCacheOptions {
-    readonly maxEntries?: number;
-    readonly ttlMs?: number;
+/** Generation result */
+export declare interface GenerationResult {
+    readonly text: string;
+    readonly toolCalls: readonly ToolCall[];
+    readonly finishReason: FinishReason;
+    readonly usage?: UsageStats;
+    readonly aborted: boolean;
 }
 
-/**
- * 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.
  *
@@ -451,6 +467,18 @@ export declare function isErr<T, E>(result: Result<T, E>): result is Err<E>;
  */
 export declare function isOk<T, E>(result: Result<T, E>): result is Ok<T>;
 
+/**
+ * Check if a value is a single ToolCall (not an array).
+ *
+ * @param value - Value to check
+ * @returns True if the value is a single ToolCall
+ */
+export declare function isToolCall(value: unknown): value is {
+    id: string;
+    name: string;
+    arguments: unknown;
+};
+
 /** JSON Schema 7 subset for tool parameters */
 export declare interface JSONSchema7 {
     readonly type?: string | readonly string[];
@@ -505,9 +533,31 @@ export declare function map<T, U, E>(result: Result<T, E>, fn: (value: T) => U):
  */
 export declare function mapErr<T, E, F>(result: Result<T, E>, fn: (error: E) => F): Result<T, F>;
 
+/** Message object */
+export declare interface Message {
+    readonly id: string;
+    readonly role: MessageRole;
+    readonly content: MessageContent;
+    readonly createdAt: number;
+    readonly metadata?: MessageMetadata;
+}
+
+/** Message content types */
+export declare type MessageContent = string | ToolCallContent | ToolResultContent;
+
+/** Message metadata */
+export declare interface MessageMetadata {
+    readonly model?: string;
+    readonly tokenCount?: number;
+    readonly finishReason?: FinishReason;
+}
+
+/** Message role */
+export declare type MessageRole = 'system' | 'user' | 'assistant' | 'tool';
+
 /**
  * Minimal database access interface for cross-package adapters.
- * Used by vectorstore persistence adapters to access IndexedDB without
+ * Used by persistence adapters to access IndexedDB without
  * creating a hard dependency on the indexeddb package.
  */
 export declare interface MinimalDatabaseAccess<T = unknown> {
@@ -516,7 +566,7 @@ export declare interface MinimalDatabaseAccess<T = unknown> {
 
 /**
  * Minimal directory access interface for cross-package adapters.
- * Used by vectorstore OPFS persistence adapters without creating
+ * Used by OPFS persistence adapters without creating
  * a hard dependency on the filesystem package.
  */
 export declare interface MinimalDirectoryAccess {
@@ -576,15 +626,9 @@ export declare interface Ok<T> {
  */
 export declare function ok<T>(value: T): Ok<T>;
 
-/** 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.
+ * Packages extend this to define their error structure.
  *
  * @example
  * ```ts
@@ -599,6 +643,39 @@ export declare interface PackageErrorData<TCode extends string> {
     readonly cause?: Error;
 }
 
+/**
+ * Priority adapter interface.
+ * Provides priority weights and comparison logic.
+ * Implemented in @mikesaintsg/adapters.
+ */
+export declare interface PriorityAdapterInterface {
+    /** Get numeric weight for a priority level. Higher values = more important. */
+    getWeight(priority: FramePriority): number;
+    /** Compare two frames by priority */
+    compare(a: ContextFrame, b: ContextFrame): number;
+}
+
+/**
+ * Provider adapter interface - LLM provider integration.
+ * Implemented for each supported provider (OpenAI, Anthropic, etc.).
+ */
+export declare interface ProviderAdapterInterface {
+    /** Get adapter identifier */
+    getId(): string;
+    /**
+     * Generate completion.
+     * @param messages - Messages to send
+     * @param options - Generation options
+     */
+    generate(messages: readonly Message[], options: GenerationOptions): StreamHandleInterface;
+    /** Check if provider supports tools */
+    supportsTools(): boolean;
+    /** Check if provider supports streaming */
+    supportsStreaming(): boolean;
+    /** Get all capabilities */
+    getCapabilities(): ProviderCapabilities;
+}
+
 /** Provider capabilities information */
 export declare interface ProviderCapabilities {
     readonly supportsTools: boolean;
@@ -614,7 +691,42 @@ export declare interface PruneResult {
     readonly remainingCount: number;
 }
 
-/** Result union */
+/**
+ * Rate limit adapter interface.
+ * Controls request rate to external services.
+ */
+export declare interface RateLimitAdapterInterface {
+    /** Acquire a request slot, waits if none available */
+    acquire(): Promise<void>;
+    /** Release a request slot */
+    release(): void;
+    /** Get current rate limit state */
+    getState(): RateLimitState;
+    /** Dynamically adjust rate limit (e.g., from Retry-After header) */
+    setLimit(requestsPerMinute: number): void;
+}
+
+/** Rate limit state */
+export declare interface RateLimitState {
+    readonly activeRequests: number;
+    readonly maxConcurrent: number;
+    readonly requestsInWindow: number;
+    readonly requestsPerMinute: number;
+    readonly windowResetIn: number;
+}
+
+/**
+ * Reranker adapter interface.
+ * Reranks search results using a cross-encoder or similar model.
+ */
+export declare interface RerankerAdapterInterface {
+    /** Rerank documents for a given query */
+    rerank(query: string, docs: readonly ScoredResult[]): Promise<readonly ScoredResult[]>;
+    /** Get the model ID used for reranking */
+    getModelId(): string;
+}
+
+/** Result union - discriminated union for operation results */
 export declare type Result<T, E> = Ok<T> | Err<E>;
 
 /** Default retrieval limit for retrieval tool */
@@ -624,7 +736,7 @@ export declare const RETRIEVAL_DEFAULT_LIMIT = 10;
 export declare const RETRIEVAL_MAX_LIMIT = 100;
 
 /** Retrieval tool created by factory */
-export declare interface RetrievalToolCreated {
+export declare interface RetrievalToolInterface {
     readonly schema: ToolSchema;
     readonly handler: (args: Readonly<Record<string, unknown>>) => Promise<readonly unknown[]>;
 }
@@ -642,6 +754,21 @@ export declare interface RetrievalToolOptions<TMetadata = unknown> {
     readonly buildFilter?: (params: Readonly<Record<string, unknown>>) => TMetadata | undefined;
 }
 
+/**
+ * Retry adapter interface.
+ * Determines retry behavior for failed operations.
+ */
+export declare interface RetryAdapterInterface {
+    /** Determine if an error should trigger a retry */
+    shouldRetry(error: unknown, attempt: number): boolean;
+    /** Get delay before next retry attempt (ms) */
+    getDelay(attempt: number): number;
+    /** Maximum number of retry attempts */
+    getMaxAttempts(): number;
+    /** Optional callback before each retry */
+    onRetry?(error: unknown, attempt: number, delayMs: number): void;
+}
+
 /** Scored result from similarity search or retrieval */
 export declare interface ScoredResult {
     readonly id: string;
@@ -704,6 +831,28 @@ export declare interface SessionPersistenceOptions {
     readonly onSaveError?: (error: unknown, sessionId: string) => void;
 }
 
+/**
+ * Determine if form dirty guard should be skipped for a navigation.
+ *
+ * @param to - Target page
+ * @param from - Source page
+ * @param excludePages - Pages to exclude from guard
+ * @param onlyFromPages - Only guard from these pages (if specified)
+ * @returns True if guard should be skipped
+ */
+export declare function shouldSkipFormGuard<TPage extends string>(to: TPage, from: TPage, excludePages: readonly TPage[], onlyFromPages: readonly TPage[] | undefined): boolean;
+
+/**
+ * Similarity adapter interface.
+ * Computes similarity between embedding vectors.
+ */
+export declare interface SimilarityAdapterInterface {
+    /** Compute similarity score between two embeddings */
+    compute(a: Embedding, b: Embedding): number;
+    /** Name of the similarity function */
+    readonly name: string;
+}
+
 /** Storage information (quota and usage) */
 export declare interface StorageInfo {
     readonly usage: number;
@@ -723,11 +872,39 @@ export declare interface StoredDocument {
     readonly updatedAt?: number;
 }
 
+/**
+ * Stream handle interface - async iteration over tokens.
+ * Provides streaming access to generation with abort control.
+ */
+export declare interface StreamHandleInterface {
+    /** Request identifier */
+    readonly requestId: string;
+    /** Async iteration */
+    [Symbol.asyncIterator](): AsyncIterator<string>;
+    /** Get final result */
+    result(): Promise<GenerationResult>;
+    /** Abort generation */
+    abort(): void;
+    /** Subscribe to tokens */
+    onToken(callback: (token: string) => void): Unsubscribe;
+    /** Subscribe to completion */
+    onComplete(callback: (result: GenerationResult) => void): Unsubscribe;
+    /** Subscribe to errors */
+    onError(callback: (error: Error) => void): Unsubscribe;
+}
+
 /** 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;
 };
 
+/** Timeout options for generation */
+export declare interface TimeoutOptions {
+    readonly requestMs?: number;
+    readonly streamMs?: number;
+    readonly tokenMs?: number;
+}
+
 /** Token budget level */
 export declare type TokenBudgetLevel = 'ok' | 'warning' | 'critical' | 'exceeded';
 
@@ -741,11 +918,43 @@ export declare interface TokenBudgetState {
     readonly level: TokenBudgetLevel;
 }
 
+/**
+ * Token counter interface for model-specific token counting.
+ * Provides estimation of token counts for context window management,
+ * cost estimation, and truncation decisions.
+ */
+export declare interface TokenCounterInterface {
+    /**
+     * Count tokens in text for specific model.
+     * @param text - Text to count tokens in
+     * @param model - Model to use for counting
+     */
+    countTokens(text: string, model: string): number;
+    /**
+     * Count tokens in messages array.
+     * @param messages - Messages to count
+     * @param model - Model to use for counting
+     */
+    countMessages(messages: readonly Message[], model: string): number;
+    /**
+     * Estimate if content fits in context window.
+     * @param content - Content to check
+     * @param model - Model to check against
+     * @param maxTokens - Maximum tokens allowed
+     */
+    fitsInContext(content: string, model: string, maxTokens: number): boolean;
+    /**
+     * Get model's context window size.
+     * @param model - Model name
+     */
+    getContextWindowSize(model: string): number | undefined;
+}
+
 /** Tool call from LLM response */
 export declare interface ToolCall {
     readonly id: string;
     readonly name: string;
-    readonly arguments: Record<string, unknown>;
+    readonly arguments: Readonly<Record<string, unknown>>;
 }
 
 /**
@@ -753,8 +962,15 @@ export declare interface ToolCall {
  * Connects inference tool calls to contextprotocol tool registry.
  */
 export declare interface ToolCallBridgeInterface {
-    execute(toolCall: ToolCall): Promise<ToolResult>;
-    executeAll(toolCalls: readonly ToolCall[]): Promise<readonly ToolResult[]>;
+    /**
+     * Execute tool call(s).
+     * Accepts single call or array of calls.
+     * @param toolCalls - Single tool call or array of calls
+     * @returns Single result or array of results
+     */
+    execute(toolCalls: ToolCall): Promise<ToolResult>;
+    execute(toolCalls: readonly ToolCall[]): Promise<readonly ToolResult[]>;
+    /** Check if tool exists */
     hasTool(name: string): boolean;
 }
 
@@ -767,14 +983,23 @@ export declare interface ToolCallBridgeOptions {
     readonly onAfterExecute?: (toolCall: ToolCall, result: unknown) => void;
 }
 
+/** Tool call content */
+export declare interface ToolCallContent {
+    readonly type: 'tool_calls';
+    readonly toolCalls: readonly ToolCall[];
+}
+
 /**
  * Tool format adapter interface.
  * Converts between internal tool representations and provider-specific formats.
  * Implemented in @mikesaintsg/adapters.
  */
 export declare interface ToolFormatAdapterInterface {
+    /** Convert tool schemas to provider-specific format */
     formatSchemas(schemas: readonly ToolSchema[]): unknown;
+    /** Parse tool calls from provider response */
     parseToolCalls(response: unknown): readonly ToolCall[];
+    /** Format tool result for provider */
     formatResult(result: ToolResult): unknown;
 }
 
@@ -796,6 +1021,14 @@ export declare interface ToolResult {
     readonly error?: string;
 }
 
+/** Tool result content */
+export declare interface ToolResultContent {
+    readonly type: 'tool_result';
+    readonly callId: string;
+    readonly name: string;
+    readonly result: unknown;
+}
+
 /** Tool schema definition */
 export declare interface ToolSchema {
     readonly name: string;
@@ -804,6 +1037,18 @@ export declare interface ToolSchema {
     readonly returns?: JSONSchema7;
 }
 
+/**
+ * Truncation adapter interface.
+ * Determines which frames to remove when budget is exceeded.
+ * Implemented in @mikesaintsg/adapters.
+ */
+export declare interface TruncationAdapterInterface {
+    /** Sort frames for truncation order. Frames at the end are removed first. */
+    sort(frames: readonly ContextFrame[]): readonly ContextFrame[];
+    /** Check if a frame should be preserved regardless of truncation */
+    shouldPreserve(frame: ContextFrame): boolean;
+}
+
 /** Truncation information */
 export declare interface TruncationInfo {
     readonly originalFrameCount: number;
@@ -818,6 +1063,13 @@ export declare type TruncationReason = 'budget_exceeded' | 'priority_too_low' |
 /** Truncation strategy */
 export declare type TruncationStrategy = 'priority' | 'fifo' | 'lifo' | 'score' | 'custom';
 
+/**
+ * @mikesaintsg/core
+ *
+ * Shared type definitions for the @mikesaintsg ecosystem.
+ * Contains ONLY types and interfaces — no implementations.
+ * All public types and interfaces are defined here as the SOURCE OF TRUTH.
+ */
 /** Cleanup function returned by event subscriptions */
 export declare type Unsubscribe = () => void;
 
@@ -851,6 +1103,13 @@ export declare function unwrap<T, E>(result: Result<T, E>, defaultValue: T): T;
  */
 export declare function unwrapOrThrow<T, E>(result: Result<T, E>): T;
 
+/** Token usage statistics */
+export declare interface UsageStats {
+    readonly promptTokens: number;
+    readonly completionTokens: number;
+    readonly totalTokens: number;
+}
+
 /** VectorStore metadata for persistence */
 export declare interface VectorStoreMetadata {
     readonly dimensions: number;