@mikesaintsg/core 0.0.2 → 0.0.3

package/README.md

@@ -13,7 +13,9 @@
 - ✅ **Shared Types** — Contracts used across multiple packages
 - ✅ **Result Pattern** — Functional error handling (`ok`, `err`, `map`, `chain`)
 - ✅ **Bridge Functions** — Connect packages without circular dependencies
-- ✅ **Interface Definitions** — Embedding, tool format, and persistence adapters
+- ✅ **Adapter Interfaces** — Embedding, tool format, persistence, and policy adapters
+- ✅ **Base Error Class** — `EcosystemError` for all package-specific errors
+- ✅ **Content Hashing** — SHA-256 based deduplication support
 - ✅ **Zero dependencies** — Built on native platform APIs
 - ✅ **TypeScript first** — Full type safety with generics
 - ✅ **Tree-shakeable** — ESM-only, import what you need
@@ -30,6 +32,8 @@ npm install @mikesaintsg/core
 
 ## Quick Start
 
+### Result Pattern
+
 ```ts
 import { ok, err, isOk, map, chain } from '@mikesaintsg/core'
 import type { Result } from '@mikesaintsg/core'
@@ -55,6 +59,33 @@ function parse(s: string): Result<number, string> {
 const result = chain(ok('42'), parse) // ok(42)
 ```
 
+### Content Hashing
+
+```ts
+import { computeContentHash } from '@mikesaintsg/core'
+
+const hash = await computeContentHash('Hello, world!')
+// 'a591a6d40bf420404a011733cfb7b190d62c65bf0bcda32b57b277d9ad9f146e'
+```
+
+### Tool Call Bridge
+
+```ts
+import { createToolCallBridge } from '@mikesaintsg/core'
+
+const bridge = createToolCallBridge({
+  registry,
+  timeout: 30000,
+  onError: (error, toolCall) => console.error(error),
+})
+
+// Execute single call
+const result = await bridge.execute(toolCall)
+
+// Execute multiple calls in parallel
+const results = await bridge.execute([call1, call2, call3])
+```
+
 ---
 
 ## Documentation
@@ -64,7 +95,6 @@ const result = chain(ok('42'), parse) // ok(42)
 ### Key Sections
 
 - [Introduction](./guides/core.md#introduction) — Value proposition and use cases
-- [Quick Start](./guides/core.md#quick-start) — Get started in minutes
 - [Core Concepts](./guides/core.md#core-concepts) — Understand the fundamentals
 - [Result Pattern](./guides/core.md#result-pattern) — Functional error handling
 - [Bridge Interfaces](./guides/core.md#bridge-interfaces) — Cross-package communication
@@ -76,17 +106,33 @@ const result = chain(ok('42'), parse) // ok(42)
 
 ### Result Functions
 
-| Function                  | Description                |
-|---------------------------|----------------------------|
-| `ok(value)`               | Create a success result    |
-| `err(error)`              | Create a failure result    |
-| `isOk(result)`            | Check if result is success |
-| `isErr(result)`           | Check if result is failure |
-| `unwrap(result, default)` | Get value or default       |
-| `map(result, fn)`         | Transform success value    |
-| `chain(result, fn)`       | Chain results (flatMap)    |
+| Function                     | Description                  |
+|------------------------------|------------------------------|
+| `ok(value)`                  | Create a success result      |
+| `err(error)`                 | Create a failure result      |
+| `isOk(result)`               | Check if result is success   |
+| `isErr(result)`              | Check if result is failure   |
+| `unwrap(result, default)`    | Get value or default         |
+| `unwrapOrThrow(result)`      | Get value or throw error     |
+| `map(result, fn)`            | Transform success value      |
+| `mapErr(result, fn)`         | Transform error value        |
+| `chain(result, fn)`          | Chain results (flatMap)      |
+
+### Content Hashing
 
-### Bridge Functions
+| Function                     | Description                  |
+|------------------------------|------------------------------|
+| `computeContentHash(text)`   | SHA-256 hash for text        |
+
+### Bridge Helper Functions
+
+| Function                     | Description                       |
+|------------------------------|-----------------------------------|
+| `isToolCall(value)`          | Type guard for ToolCall objects   |
+| `shouldSkipFormGuard(...)`   | Check if form guard should skip   |
+| `formatScoredResult(result)` | Default result formatter          |
+
+### Factory Functions
 
 | Function                            | Description                      |
 |-------------------------------------|----------------------------------|
@@ -95,15 +141,57 @@ const result = chain(ok('42'), parse) // ok(42)
 | `createFormDirtyGuard(options)`     | Navigation guard for dirty forms |
 | `createSessionPersistence(options)` | Session storage adapter          |
 
+### Error Handling
+
+| Export                 | Description                        |
+|------------------------|------------------------------------|
+| `EcosystemError`       | Base error class for all packages  |
+| `isEcosystemError(e)`  | Type guard for ecosystem errors    |
+
 ### Shared Types
 
-| Type                         | Description                     |
-|------------------------------|---------------------------------|
-| `Result<T, E>`               | Success or failure union        |
-| `Unsubscribe`                | Cleanup function type           |
-| `EmbeddingAdapterInterface`  | Embedding generation contract   |
-| `ToolFormatAdapterInterface` | Tool format conversion          |
-| `BuiltContext`               | Assembled context for inference |
+| Type                                      | Description                           |
+|-------------------------------------------|---------------------------------------|
+| `Result<T, E>`                            | Success or failure union              |
+| `Ok<T>`, `Err<E>`                         | Result discriminants                  |
+| `Unsubscribe`                             | Cleanup function type                 |
+| `DestroyFn`                               | Resource cleanup function             |
+| `SubscriptionToHook<T>`                   | Convert subscriptions to hooks        |
+| `Embedding`                               | Float32Array embedding vector         |
+| `ToolCall`, `ToolResult`, `ToolSchema`    | Tool-related types                    |
+| `ScoredResult`                            | Search result with score              |
+| `ContextFrame`, `BuiltContext`            | Context management types              |
+| `TokenBudgetState`, `TokenBudgetLevel`    | Token budget types                    |
+
+### Adapter Interfaces
+
+| Interface                                 | Category      | Description                    |
+|-------------------------------------------|---------------|--------------------------------|
+| `EmbeddingAdapterInterface`               | Source        | Embedding generation           |
+| `ToolFormatAdapterInterface`              | Transform     | Provider tool formatting       |
+| `SimilarityAdapterInterface`              | Transform     | Vector similarity computation  |
+| `DeduplicationAdapterInterface`           | Transform     | Frame deduplication            |
+| `TruncationAdapterInterface`              | Transform     | Context truncation             |
+| `PriorityAdapterInterface`                | Transform     | Frame priority ordering        |
+| `RetryAdapterInterface`                   | Policy        | Retry behavior                 |
+| `RateLimitAdapterInterface`               | Policy        | Rate limiting                  |
+| `EmbeddingCacheAdapterInterface`          | Enhancement   | Embedding caching              |
+| `BatchAdapterInterface`                   | Enhancement   | Batch processing               |
+| `RerankerAdapterInterface`                | Enhancement   | Result reranking               |
+| `VectorStorePersistenceAdapterInterface`  | Persistence   | Vector storage                 |
+
+### Minimal Cross-Package Interfaces
+
+| Interface                   | Description                          |
+|-----------------------------|--------------------------------------|
+| `MinimalDatabaseAccess<T>`  | IndexedDB access without dependency  |
+| `MinimalStoreAccess<T>`     | Store operations interface           |
+| `MinimalDirectoryAccess`    | OPFS directory access                |
+| `MinimalFileAccess`         | OPFS file access                     |
+| `ToolRegistryMinimal`       | Tool registry without dependency     |
+| `VectorStoreMinimal<T>`     | Vector store without dependency      |
+| `FormMinimal<T>`            | Form state without dependency        |
+| `SerializableSession`       | Session serialization interface      |
 
 ---
 
@@ -112,7 +200,7 @@ const result = chain(ok('42'), parse) // ok(42)
 ### Result Pattern
 
 ```ts
-import { ok, err, isOk, unwrap } from '@mikesaintsg/core'
+import { ok, err, isOk, unwrap, map, chain } from '@mikesaintsg/core'
 
 function divide(a: number, b: number) {
   if (b === 0) return err('DIVISION_BY_ZERO')
@@ -121,52 +209,109 @@ function divide(a: number, b: number) {
 
 const result = divide(10, 2)
 const value = unwrap(result, 0) // 5
+
+// Chain operations
+const doubled = chain(divide(10, 2), n => ok(n * 2)) // ok(10)
 ```
 
-### Tool Call Bridge
+### Custom Error Class
 
 ```ts
-import { createToolCallBridge } from '@mikesaintsg/core'
+import { EcosystemError, isEcosystemError } from '@mikesaintsg/core'
 
-const bridge = createToolCallBridge({
-  registry,
-  timeout: 30000,
-  onError: (error, toolCall) => console.error(error),
+type StorageErrorCode = 'NOT_FOUND' | 'QUOTA_EXCEEDED' | 'WRITE_FAILED'
+
+class StorageError extends EcosystemError {
+  readonly code: StorageErrorCode
+
+  constructor(code: StorageErrorCode, message: string, cause?: Error) {
+    super(message, cause)
+    this.code = code
+  }
+}
+
+try {
+  throw new StorageError('NOT_FOUND', 'Document not found')
+} catch (error) {
+  if (isEcosystemError(error)) {
+    console.log(error.code) // 'NOT_FOUND'
+  }
+}
+```
+
+### Retrieval Tool
+
+```ts
+import { createRetrievalTool } from '@mikesaintsg/core'
+
+const { schema, handler } = createRetrievalTool({
+  vectorStore,
+  name: 'search_docs',
+  description: 'Search documentation for relevant information',
+  defaultLimit: 5,
+  scoreThreshold: 0.7,
 })
 
-const result = await bridge.execute(toolCall)
+// Register with tool registry
+registry.register(schema, handler)
 ```
 
-### With TypeScript
+### Session Persistence
 
 ```ts
-import type { 
-  EmbeddingAdapterInterface, 
-  Result 
-} from '@mikesaintsg/core'
+import { createSessionPersistence } from '@mikesaintsg/core'
 
-// Type-safe adapter interface
-const adapter: EmbeddingAdapterInterface = createAdapter()
+const persistence = createSessionPersistence({
+  database,
+  storeName: 'chat_sessions',
+  autoprune: 7 * 24 * 60 * 60 * 1000, // 7 days
+})
 
-// Inferred result types
-function safeParse(input: string): Result<number, 'PARSE_ERROR'> {
-  const n = parseInt(input, 10)
-  return isNaN(n) ? err('PARSE_ERROR') : ok(n)
-}
+await persistence.save('session-1', session)
+const loaded = await persistence.load('session-1')
 ```
 
+### Form Dirty Guard
+
+```ts
+import { createFormDirtyGuard } from '@mikesaintsg/core'
+
+const guard = createFormDirtyGuard({
+  form,
+  confirmFn: (message) => window.confirm(message),
+  message: 'You have unsaved changes. Continue?',
+  excludePages: ['logout'],
+})
+
+router.beforeNavigate(guard)
+```
+
+---
+
+## Constants
+
+| Constant                     | Value  | Description                    |
+|------------------------------|--------|--------------------------------|
+| `BRIDGE_DEFAULT_TIMEOUT`     | 30000  | Default bridge timeout (ms)    |
+| `RETRIEVAL_DEFAULT_LIMIT`    | 10     | Default retrieval result limit |
+| `RETRIEVAL_MAX_LIMIT`        | 100    | Maximum retrieval result limit |
+| `FORM_DIRTY_DEFAULT_MESSAGE` | string | Default form guard message     |
+
 ---
 
 ## Ecosystem Integration
 
 | Package                        | Integration                                    |
 |--------------------------------|------------------------------------------------|
-| `@mikesaintsg/adapters`        | Provider and embedding adapter implementations |
+| `@mikesaintsg/adapters`        | Implements adapter interfaces                  |
 | `@mikesaintsg/inference`       | Uses shared types and bridge functions         |
 | `@mikesaintsg/vectorstore`     | Uses embedding and persistence interfaces      |
 | `@mikesaintsg/contextprotocol` | Uses tool types and registry interface         |
+| `@mikesaintsg/contextbuilder`  | Uses context frame and budget types            |
+| `@mikesaintsg/indexeddb`       | Implements MinimalDatabaseAccess               |
+| `@mikesaintsg/filesystem`      | Implements MinimalDirectoryAccess              |
 
-See [Integration Patterns](./guides/core.md#integration-patterns) for details.
+See [Integration Guide](./guides/integration.md) for detailed patterns.
 
 ---
 

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.
  *
@@ -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;
+    /** Optional: Get cache statistics */
+    getStats?(): CacheStats;
 }
 
-/** 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 */
+/** 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,23 @@ 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'];
 
 /** 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>;
@@ -352,54 +381,6 @@ export declare interface FrameSummary {
 /** 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 model?: string;
-    readonly temperature?: number;
-    readonly maxTokens?: number;
-    readonly topP?: number;
-    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;
-}
-
-/** 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.
  *
@@ -451,6 +432,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[];
@@ -507,7 +500,7 @@ export declare function mapErr<T, E, F>(result: Result<T, E>, fn: (error: E) =>
 
 /**
  * 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 +509,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 +569,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,13 +586,16 @@ export declare interface PackageErrorData<TCode extends string> {
     readonly cause?: Error;
 }
 
-/** Provider capabilities information */
-export declare interface ProviderCapabilities {
-    readonly supportsTools: boolean;
-    readonly supportsStreaming: boolean;
-    readonly supportsVision: boolean;
-    readonly supportsFunctions: boolean;
-    readonly models: readonly string[];
+/**
+ * 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;
 }
 
 /** Prune result information */
@@ -614,7 +604,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 */
@@ -642,6 +667,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 +744,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;
@@ -745,7 +807,7 @@ export declare interface TokenBudgetState {
 export declare interface ToolCall {
     readonly id: string;
     readonly name: string;
-    readonly arguments: Record<string, unknown>;
+    readonly arguments: Readonly<Record<string, unknown>>;
 }
 
 /**
@@ -753,8 +815,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;
 }
 
@@ -773,8 +842,11 @@ export declare interface ToolCallBridgeOptions {
  * 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;
 }
 
@@ -804,6 +876,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 +902,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;
 

package/dist/index.js

@@ -1,35 +1,26 @@
-class x extends Error {
-  cause;
-  constructor(t, o) {
-    super(t), this.name = this.constructor.name, this.cause = o;
-  }
-}
-function F(e) {
-  return e instanceof x;
-}
 class A extends Error {
-  code;
+  /** Original error that caused this one */
   cause;
-  constructor(t, o, s) {
-    super(o), this.name = "CoreError", this.code = t, this.cause = s;
+  constructor(t, s) {
+    super(t), this.name = this.constructor.name, this.cause = s;
   }
 }
-function P(e) {
+function b(e) {
   return e instanceof A;
 }
 function S(e) {
   return { ok: !0, value: e };
 }
-function I(e) {
+function l(e) {
   return { ok: !1, error: e };
 }
-function b(e) {
+function F(e) {
   return e.ok === !0;
 }
-function q(e) {
+function P(e) {
   return !e.ok;
 }
-function O(e, t) {
+function q(e, t) {
   return e.ok ? e.value : t;
 }
 function U(e) {
@@ -41,23 +32,36 @@ function B(e, t) {
   return e.ok ? S(t(e.value)) : e;
 }
 function G(e, t) {
-  return e.ok ? e : I(t(e.error));
+  return e.ok ? e : l(t(e.error));
 }
-function $(e, t) {
+function O(e, t) {
   return e.ok ? t(e.value) : e;
 }
-async function j(e) {
-  const o = new TextEncoder().encode(e), s = await crypto.subtle.digest("SHA-256", o);
-  return Array.from(new Uint8Array(s)).map((a) => a.toString(16).padStart(2, "0")).join("");
+async function $(e) {
+  const s = new TextEncoder().encode(e), a = await crypto.subtle.digest("SHA-256", s);
+  return Array.from(new Uint8Array(a)).map((o) => o.toString(16).padStart(2, "0")).join("");
 }
-const k = 3e4, M = 10, R = 100, L = "You have unsaved changes. Are you sure you want to leave?";
-function H(e) {
+function I(e) {
+  return typeof e == "object" && e !== null && "id" in e && "name" in e && "arguments" in e;
+}
+function k(e, t, s, a) {
+  return !!(s.includes(e) || a !== void 0 && !a.includes(t));
+}
+function M(e) {
+  return {
+    content: e.content,
+    score: e.score,
+    metadata: e.metadata
+  };
+}
+const R = 3e4, L = 10, _ = 100, D = "You have unsaved changes. Are you sure you want to leave?";
+function j(e) {
   const {
     registry: t,
-    timeout: o = k,
-    onError: s,
-    onBeforeExecute: i,
-    onAfterExecute: a
+    timeout: s = R,
+    onError: a,
+    onBeforeExecute: c,
+    onAfterExecute: o
   } = e;
   async function u(r) {
     if (!t.has(r.name))
@@ -67,40 +71,37 @@ function H(e) {
         success: !1,
         error: `Tool not found: ${r.name}`
       };
-    i?.(r);
+    c?.(r);
     try {
       const n = new Promise((f, m) => {
         setTimeout(() => {
-          m(new Error(`Tool execution timed out after ${o}ms`));
-        }, o);
-      }), c = await Promise.race([
+          m(new Error(`Tool execution timed out after ${s}ms`));
+        }, s);
+      }), i = await Promise.race([
         t.execute(r.name, r.arguments),
         n
       ]);
-      return a?.(r, c), {
+      return o?.(r, i), {
         callId: r.id,
         name: r.name,
         success: !0,
-        value: c
+        value: i
       };
     } catch (n) {
-      s?.(n, r);
-      const c = n instanceof Error ? n.message : String(n);
+      a?.(n, r);
+      const i = n instanceof Error ? n.message : String(n);
       return {
         callId: r.id,
         name: r.name,
         success: !1,
-        error: c
+        error: i
       };
     }
   }
   return {
-    async execute(r) {
-      return u(r);
-    },
-    async executeAll(r) {
-      return await Promise.all(
-        r.map((c) => u(c))
+    execute(r) {
+      return I(r) ? u(r) : Promise.all(
+        r.map((n) => u(n))
       );
     },
     hasTool(r) {
@@ -108,17 +109,17 @@ function H(e) {
     }
   };
 }
-function N(e) {
+function H(e) {
   const {
     vectorStore: t,
-    name: o,
-    description: s,
-    defaultLimit: i = M,
-    maxLimit: a = R,
+    name: s,
+    description: a,
+    defaultLimit: c = L,
+    maxLimit: o = _,
     scoreThreshold: u,
-    formatResult: r = _,
+    formatResult: r = M,
     extendParameters: n = {},
-    buildFilter: c
+    buildFilter: i
   } = e, f = {
     type: "object",
     properties: {
@@ -128,17 +129,17 @@ function N(e) {
       },
       limit: {
         type: "integer",
-        description: `Maximum number of results to return (default: ${i}, max: ${a})`,
+        description: `Maximum number of results to return (default: ${c}, max: ${o})`,
         minimum: 1,
-        maximum: a,
-        default: i
+        maximum: o,
+        default: c
       },
       ...n
     },
     required: ["query"]
   }, m = {
-    name: o,
-    description: s,
+    name: s,
+    description: a,
     parameters: f
   };
   async function d(h) {
@@ -146,73 +147,62 @@ function N(e) {
     if (typeof y != "string" || y.length === 0)
       return [];
     const p = h.limit;
-    let E = i;
-    typeof p == "number" && Number.isInteger(p) && (E = Math.min(Math.max(1, p), a));
-    const l = c?.(h), v = l !== void 0 ? { limit: E, filter: l } : { limit: E }, w = await t.search(y, v);
-    let g = w;
-    return u !== void 0 && (g = w.filter((T) => T.score >= u)), g.map(r);
+    let E = c;
+    typeof p == "number" && Number.isInteger(p) && (E = Math.min(Math.max(1, p), o));
+    const w = i?.(h), v = w !== void 0 ? { limit: E, filter: w } : { limit: E }, g = await t.search(y, v);
+    let T = g;
+    return u !== void 0 && (T = g.filter((x) => x.score >= u)), T.map(r);
   }
   return { schema: m, handler: d };
 }
-function _(e) {
-  return {
-    content: e.content,
-    score: e.score,
-    metadata: e.metadata
-  };
-}
-function V(e) {
+function N(e) {
   const {
     form: t,
-    confirmFn: o,
-    message: s = L,
-    excludePages: i = [],
-    onlyFromPages: a
+    confirmFn: s,
+    message: a = D,
+    excludePages: c = [],
+    onlyFromPages: o
   } = e;
   return async function(r, n) {
-    return D(r, n, i, a) || !t.isDirty() ? !0 : await Promise.resolve(o(s));
+    return k(r, n, c, o) || !t.isDirty() ? !0 : Promise.resolve(s(a));
   };
 }
-function D(e, t, o, s) {
-  return !!(o.includes(e) || s !== void 0 && !s.includes(t));
-}
-function Y(e) {
+function V(e) {
   const {
     database: t,
-    storeName: o,
-    autoprune: s,
-    onSaveError: i
-  } = e, a = t.store(o);
-  s !== void 0 && s > 0 && u(s);
+    storeName: s,
+    autoprune: a,
+    onSaveError: c
+  } = e, o = t.store(s);
   async function u(r) {
-    const c = Date.now() - r, f = await a.all();
+    const i = Date.now() - r, f = await o.all();
     let m = 0;
     for (const d of f)
-      d.updatedAt < c && (await a.remove(d.id), m++);
+      d.updatedAt < i && (await o.remove(d.id), m++);
     return m;
   }
-  return {
+  return a !== void 0 && a > 0 && u(a), {
     async save(r, n) {
       try {
-        const c = {
+        const i = {
           id: r,
           messages: [...n.getMessages()],
           metadata: n.getMetadata(),
           updatedAt: Date.now()
         };
-        await a.set(c, r);
-      } catch (c) {
-        throw i?.(c, r), c;
+        await o.set(i, r);
+      } catch (i) {
+        throw c?.(i, r), i;
       }
     },
     async load(r) {
-      return a.get(r);
+      return o.get(r);
     },
     async delete(r) {
-      await a.remove(r);
+      await o.remove(r);
     },
     async list() {
-      return (await a.all()).map((n) => n.id);
+      return (await o.all()).map((n) => n.id);
     },
     async prune(r) {
       return u(r);
@@ -220,27 +210,28 @@ function Y(e) {
   };
 }
 export {
-  k as BRIDGE_DEFAULT_TIMEOUT,
-  A as CoreError,
-  x as EcosystemError,
-  L as FORM_DIRTY_DEFAULT_MESSAGE,
-  M as RETRIEVAL_DEFAULT_LIMIT,
-  R as RETRIEVAL_MAX_LIMIT,
-  $ as chain,
-  j as computeContentHash,
-  V as createFormDirtyGuard,
-  N as createRetrievalTool,
-  Y as createSessionPersistence,
-  H as createToolCallBridge,
-  I as err,
-  P as isCoreError,
-  F as isEcosystemError,
-  q as isErr,
-  b as isOk,
+  R as BRIDGE_DEFAULT_TIMEOUT,
+  A as EcosystemError,
+  D as FORM_DIRTY_DEFAULT_MESSAGE,
+  L as RETRIEVAL_DEFAULT_LIMIT,
+  _ as RETRIEVAL_MAX_LIMIT,
+  O as chain,
+  $ as computeContentHash,
+  N as createFormDirtyGuard,
+  H as createRetrievalTool,
+  V as createSessionPersistence,
+  j as createToolCallBridge,
+  l as err,
+  M as formatScoredResult,
+  b as isEcosystemError,
+  P as isErr,
+  F as isOk,
+  I as isToolCall,
   B as map,
   G as mapErr,
   S as ok,
-  O as unwrap,
+  k as shouldSkipFormGuard,
+  q as unwrap,
   U as unwrapOrThrow
 };
 //# sourceMappingURL=index.js.map

package/dist/index.js.map

@@ -1 +1 @@
-{"version":3,"file":"index.js","sources":["../src/errors.ts","../src/helpers.ts","../src/constants.ts","../src/bridges/tool-call.ts","../src/bridges/retrieval-tool.ts","../src/bridges/form-dirty-guard.ts","../src/bridges/session-persistence.ts"],"sourcesContent":["/**\r\n * @mikesaintsg/core\r\n *\r\n * Error utilities and re-exports.\r\n */\r\n\r\n// ============================================================================\r\n// Base Ecosystem Error\r\n// ============================================================================\r\n\r\nimport { CoreErrorCode } from './types'\r\n\r\n/**\r\n * Base error class for all ecosystem errors.\r\n * All package-specific errors should extend this class.\r\n */\r\nexport abstract class EcosystemError extends Error {\r\n\tabstract readonly code: string\r\n\toverride readonly cause: Error | undefined\r\n\r\n\tconstructor(message: string, cause?: Error) {\r\n\t\tsuper(message)\r\n\t\tthis.name = this.constructor.name\r\n\t\tthis.cause = cause\r\n\t}\r\n}\r\n\r\n/**\r\n * Type guard for ecosystem errors.\r\n *\r\n * @param error - The value to check\r\n * @returns True if the error is an EcosystemError\r\n *\r\n * @example\r\n * ```ts\r\n * try {\r\n *   await someOperation()\r\n * } catch (error) {\r\n *   if (isEcosystemError(error)) {\r\n *     console.log('Code:', error.code)\r\n *   }\r\n * }\r\n * ```\r\n */\r\nexport function isEcosystemError(error: unknown): error is EcosystemError {\r\n\treturn error instanceof EcosystemError\r\n}\r\n\r\n// ============================================================================\r\n// Core Error Class\r\n// ============================================================================\r\n\r\n/**\r\n * Core package error.\r\n *\r\n * @example\r\n * ```ts\r\n * throw new CoreError('ADAPTER_ERROR', 'Failed to connect to OpenAI')\r\n * ```\r\n */\r\nexport class CoreError extends Error {\r\n\treadonly code: CoreErrorCode\r\n\toverride readonly cause: Error | undefined\r\n\r\n\tconstructor(code: CoreErrorCode, message: string, cause?: Error) {\r\n\t\tsuper(message)\r\n\t\tthis.name = 'CoreError'\r\n\t\tthis.code = code\r\n\t\tthis.cause = cause\r\n\t}\r\n}\r\n\r\n/**\r\n * Type guard to check if an error is a CoreError.\r\n *\r\n * @param error - The value to check\r\n * @returns True if the error is a CoreError\r\n *\r\n * @example\r\n * ```ts\r\n * try {\r\n *   await adapter.embed(['text'])\r\n * } catch (error) {\r\n *   if (isCoreError(error)) {\r\n *     console.log('Code:', error.code)\r\n *   }\r\n * }\r\n * ```\r\n */\r\nexport function isCoreError(error: unknown): error is CoreError {\r\n\treturn error instanceof CoreError\r\n}\r\n","/**\r\n * @mikesaintsg/core\r\n *\r\n * Helper functions and type guards.\r\n */\r\n\r\nimport type { Ok, Err, Result, ContentHash } from './types.js'\r\n\r\n// ============================================================================\r\n// Result Pattern Helpers\r\n// ============================================================================\r\n\r\n/**\r\n * Create a success result.\r\n *\r\n * @param value - The success value\r\n * @returns An Ok result containing the value\r\n *\r\n * @example\r\n * ```ts\r\n * const result = ok(42)\r\n * // result.ok === true\r\n * // result.value === 42\r\n * ```\r\n */\r\nexport function ok<T>(value: T): Ok<T> {\r\n\treturn { ok: true, value }\r\n}\r\n\r\n/**\r\n * Create a failure result.\r\n *\r\n * @param error - The error value\r\n * @returns An Err result containing the error\r\n *\r\n * @example\r\n * ```ts\r\n * const result = err('NOT_FOUND')\r\n * // result.ok === false\r\n * // result.error === 'NOT_FOUND'\r\n * ```\r\n */\r\nexport function err<E>(error: E): Err<E> {\r\n\treturn { ok: false, error }\r\n}\r\n\r\n/**\r\n * Check if a result is a success.\r\n *\r\n * @param result - The result to check\r\n * @returns True if the result is Ok, false otherwise\r\n *\r\n * @example\r\n * ```ts\r\n * const result: Result<number, string> = ok(42)\r\n * if (isOk(result)) {\r\n *   console.log(result.value) // TypeScript knows result is Ok<number>\r\n * }\r\n * ```\r\n */\r\nexport function isOk<T, E>(result: Result<T, E>): result is Ok<T> {\r\n\treturn result.ok === true\r\n}\r\n\r\n/**\r\n * Check if a result is a failure.\r\n *\r\n * @param result - The result to check\r\n * @returns True if the result is Err, false otherwise\r\n *\r\n * @example\r\n * ```ts\r\n * const result: Result<number, string> = err('NOT_FOUND')\r\n * if (isErr(result)) {\r\n *   console.log(result.error) // TypeScript knows result is Err<string>\r\n * }\r\n * ```\r\n */\r\nexport function isErr<T, E>(result: Result<T, E>): result is Err<E> {\r\n\treturn !result.ok\r\n}\r\n\r\n/**\r\n * Unwrap a result, returning the value or a default.\r\n *\r\n * @param result - The result to unwrap\r\n * @param defaultValue - Value to return if result is an error\r\n * @returns The success value or the default value\r\n *\r\n * @example\r\n * ```ts\r\n * const value = unwrap(ok(42), 0) // 42\r\n * const fallback = unwrap(err('oops'), 0) // 0\r\n * ```\r\n */\r\nexport function unwrap<T, E>(result: Result<T, E>, defaultValue: T): T {\r\n\treturn result.ok ? result.value : defaultValue\r\n}\r\n\r\n/**\r\n * Unwrap a result, throwing if it's an error.\r\n *\r\n * @param result - The result to unwrap\r\n * @returns The success value\r\n * @throws The error if result is Err\r\n *\r\n * @example\r\n * ```ts\r\n * const value = unwrapOrThrow(ok(42)) // 42\r\n * unwrapOrThrow(err(new Error('oops'))) // throws Error('oops')\r\n * ```\r\n */\r\nexport function unwrapOrThrow<T, E>(result: Result<T, E>): T {\r\n\tif (result.ok) {\r\n\t\treturn result.value\r\n\t}\r\n\tif (result.error instanceof Error) {\r\n\t\tthrow result.error\r\n\t}\r\n\tthrow new Error(String(result.error))\r\n}\r\n\r\n/**\r\n * Map a function over a success value.\r\n *\r\n * @param result - The result to map over\r\n * @param fn - Function to apply to the success value\r\n * @returns A new result with the mapped value, or the original error\r\n *\r\n * @example\r\n * ```ts\r\n * const doubled = map(ok(5), x => x * 2) // ok(10)\r\n * const failed = map(err('oops'), x => x * 2) // err('oops')\r\n * ```\r\n */\r\nexport function map<T, U, E>(\r\n\tresult: Result<T, E>,\r\n\tfn: (value: T) => U,\r\n): Result<U, E> {\r\n\treturn result.ok ? ok(fn(result.value)) : result\r\n}\r\n\r\n/**\r\n * Map a function over an error value.\r\n *\r\n * @param result - The result to map over\r\n * @param fn - Function to apply to the error value\r\n * @returns A new result with the mapped error, or the original value\r\n *\r\n * @example\r\n * ```ts\r\n * const wrapped = mapErr(err('oops'), e => new Error(e)) // err(Error('oops'))\r\n * const unchanged = mapErr(ok(42), e => new Error(e)) // ok(42)\r\n * ```\r\n */\r\nexport function mapErr<T, E, F>(\r\n\tresult: Result<T, E>,\r\n\tfn: (error: E) => F,\r\n): Result<T, F> {\r\n\treturn result.ok ? result : err(fn(result.error))\r\n}\r\n\r\n/**\r\n * Chain results (flatMap). Apply a function that returns a Result to a success value.\r\n *\r\n * @param result - The result to chain\r\n * @param fn - Function returning a new Result\r\n * @returns The result of applying fn, or the original error\r\n *\r\n * @example\r\n * ```ts\r\n * const parsed = chain(ok('42'), s => {\r\n *   const n = parseInt(s, 10)\r\n *   return isNaN(n) ? err('PARSE_ERROR') : ok(n)\r\n * })\r\n * // parsed = ok(42)\r\n * ```\r\n */\r\nexport function chain<T, U, E>(\r\n\tresult: Result<T, E>,\r\n\tfn: (value: T) => Result<U, E>,\r\n): Result<U, E> {\r\n\treturn result.ok ? fn(result.value) : result\r\n}\r\n\r\n// ============================================================================\r\n// Content Hashing Helpers\r\n// ============================================================================\r\n\r\n/**\r\n * Compute a SHA-256 content hash for text.\r\n *\r\n * @param text - The text to hash\r\n * @returns A hex string content hash\r\n *\r\n * @example\r\n * ```ts\r\n * const hash = await computeContentHash('Hello, world!')\r\n * // hash = 'a591a6d40bf420404a011733cfb7b190d62c65bf0bcda32b57b277d9ad9f146e'\r\n * ```\r\n */\r\nexport async function computeContentHash(text: string): Promise<ContentHash> {\r\n\tconst encoder = new TextEncoder()\r\n\tconst data = encoder.encode(text)\r\n\tconst hashBuffer = await crypto.subtle.digest('SHA-256', data)\r\n\tconst hashArray = Array.from(new Uint8Array(hashBuffer))\r\n\treturn hashArray.map(b => b.toString(16).padStart(2, '0')).join('')\r\n}\r\n","/**\r\n * @mikesaintsg/core\r\n *\r\n * Shared constants for the core library.\r\n */\r\n\r\n// ============================================================================\r\n// Bridge Constants\r\n// ============================================================================\r\n\r\n/** Default timeout for bridge operations in milliseconds */\r\nexport const BRIDGE_DEFAULT_TIMEOUT = 30000\r\n\r\n/** Default retrieval limit for retrieval tool */\r\nexport const RETRIEVAL_DEFAULT_LIMIT = 10\r\n\r\n/** Maximum retrieval limit for retrieval tool */\r\nexport const RETRIEVAL_MAX_LIMIT = 100\r\n\r\n/** Default form dirty guard message */\r\nexport const FORM_DIRTY_DEFAULT_MESSAGE = 'You have unsaved changes. Are you sure you want to leave?'\r\n","/**\r\n * @mikesaintsg/core\r\n *\r\n * Tool call bridge that connects inference tool calls to contextprotocol tool registry.\r\n */\r\n\r\nimport type {\r\n\tToolCall,\r\n\tToolResult,\r\n\tToolCallBridgeOptions,\r\n\tToolCallBridgeInterface,\r\n} from '../types.js'\r\nimport { BRIDGE_DEFAULT_TIMEOUT } from '../constants.js'\r\n\r\n/**\r\n * Create a tool call bridge.\r\n *\r\n * @param options - Bridge configuration options\r\n * @returns A tool call bridge instance\r\n *\r\n * @example\r\n * ```ts\r\n * import { createToolRegistry } from '@mikesaintsg/contextprotocol'\r\n * import { createToolCallBridge } from '@mikesaintsg/core'\r\n *\r\n * const registry = createToolRegistry()\r\n * registry.register(weatherTool)\r\n *\r\n * const bridge = createToolCallBridge({\r\n *   registry,\r\n *   timeout: 30000,\r\n *   onError: (error, toolCall) => console.error(`Tool ${toolCall.name} failed:`, error),\r\n * })\r\n *\r\n * // Execute tool calls from LLM response\r\n * const results = await bridge.executeAll(response.toolCalls)\r\n * ```\r\n */\r\nexport function createToolCallBridge(\r\n\toptions: ToolCallBridgeOptions,\r\n): ToolCallBridgeInterface {\r\n\tconst {\r\n\t\tregistry,\r\n\t\ttimeout = BRIDGE_DEFAULT_TIMEOUT,\r\n\t\tonError,\r\n\t\tonBeforeExecute,\r\n\t\tonAfterExecute,\r\n\t} = options\r\n\r\n\t/**\r\n\t * Execute a single tool call with timeout.\r\n\t */\r\n\tasync function executeWithTimeout(\r\n\t\ttoolCall: ToolCall,\r\n\t): Promise<ToolResult> {\r\n\t\t// Check if tool exists\r\n\t\tif (!registry.has(toolCall.name)) {\r\n\t\t\tconst result: ToolResult = {\r\n\t\t\t\tcallId: toolCall.id,\r\n\t\t\t\tname: toolCall.name,\r\n\t\t\t\tsuccess: false,\r\n\t\t\t\terror: `Tool not found: ${toolCall.name}`,\r\n\t\t\t}\r\n\t\t\treturn result\r\n\t\t}\r\n\r\n\t\t// Call lifecycle hook\r\n\t\tonBeforeExecute?.(toolCall)\r\n\r\n\t\ttry {\r\n\t\t\t// Create timeout promise\r\n\t\t\tconst timeoutPromise = new Promise<never>((_, reject) => {\r\n\t\t\t\tsetTimeout(() => {\r\n\t\t\t\t\treject(new Error(`Tool execution timed out after ${timeout}ms`))\r\n\t\t\t\t}, timeout)\r\n\t\t\t})\r\n\r\n\t\t\t// Execute tool with timeout\r\n\t\t\tconst value = await Promise.race([\r\n\t\t\t\tregistry.execute(toolCall.name, toolCall.arguments),\r\n\t\t\t\ttimeoutPromise,\r\n\t\t\t])\r\n\r\n\t\t\t// Call lifecycle hook\r\n\t\t\tonAfterExecute?.(toolCall, value)\r\n\r\n\t\t\treturn {\r\n\t\t\t\tcallId: toolCall.id,\r\n\t\t\t\tname: toolCall.name,\r\n\t\t\t\tsuccess: true,\r\n\t\t\t\tvalue,\r\n\t\t\t}\r\n\t\t} catch (error) {\r\n\t\t\t// Call error hook\r\n\t\t\tonError?.(error, toolCall)\r\n\r\n\t\t\tconst errorMessage = error instanceof Error\r\n\t\t\t\t? error.message\r\n\t\t\t\t: String(error)\r\n\r\n\t\t\treturn {\r\n\t\t\t\tcallId: toolCall.id,\r\n\t\t\t\tname: toolCall.name,\r\n\t\t\t\tsuccess: false,\r\n\t\t\t\terror: errorMessage,\r\n\t\t\t}\r\n\t\t}\r\n\t}\r\n\r\n\treturn {\r\n\t\tasync execute(toolCall: ToolCall): Promise<ToolResult> {\r\n\t\t\treturn executeWithTimeout(toolCall)\r\n\t\t},\r\n\r\n\t\tasync executeAll(toolCalls: readonly ToolCall[]): Promise<readonly ToolResult[]> {\r\n\t\t\t// Execute all tool calls in parallel\r\n\t\t\tconst results = await Promise.all(\r\n\t\t\t\ttoolCalls.map(toolCall => executeWithTimeout(toolCall)),\r\n\t\t\t)\r\n\t\t\treturn results\r\n\t\t},\r\n\r\n\t\thasTool(name: string): boolean {\r\n\t\t\treturn registry.has(name)\r\n\t\t},\r\n\t}\r\n}\r\n","/**\r\n * @mikesaintsg/core\r\n *\r\n * Retrieval tool factory that connects vectorstore to contextprotocol.\r\n */\r\n\r\nimport type {\r\n\tRetrievalToolOptions,\r\n\tRetrievalToolCreated,\r\n\tToolSchema,\r\n\tJSONSchema7,\r\n\tScoredResult,\r\n} from '../types.js'\r\nimport {\r\n\tRETRIEVAL_DEFAULT_LIMIT,\r\n\tRETRIEVAL_MAX_LIMIT,\r\n} from '../constants.js'\r\n\r\n/**\r\n * Create a retrieval tool for use with contextprotocol tool registry.\r\n *\r\n * @param options - Retrieval tool configuration options\r\n * @returns A tool schema and handler for registration\r\n *\r\n * @example\r\n * ```ts\r\n * import { createVectorStore } from '@mikesaintsg/vectorstore'\r\n * import { createToolRegistry } from '@mikesaintsg/contextprotocol'\r\n * import { createRetrievalTool } from '@mikesaintsg/core'\r\n *\r\n * const vectorStore = createVectorStore({ ... })\r\n * const registry = createToolRegistry()\r\n *\r\n * const { schema, handler } = createRetrievalTool({\r\n *   vectorStore,\r\n *   name: 'search_docs',\r\n *   description: 'Search documentation for relevant information',\r\n *   defaultLimit: 5,\r\n *   scoreThreshold: 0.7,\r\n * })\r\n *\r\n * registry.register({ ...schema, execute: handler })\r\n * ```\r\n */\r\nexport function createRetrievalTool<TMetadata = unknown>(\r\n\toptions: RetrievalToolOptions<TMetadata>,\r\n): RetrievalToolCreated {\r\n\tconst {\r\n\t\tvectorStore,\r\n\t\tname,\r\n\t\tdescription,\r\n\t\tdefaultLimit = RETRIEVAL_DEFAULT_LIMIT,\r\n\t\tmaxLimit = RETRIEVAL_MAX_LIMIT,\r\n\t\tscoreThreshold,\r\n\t\tformatResult = defaultFormatResult,\r\n\t\textendParameters = {},\r\n\t\tbuildFilter,\r\n\t} = options\r\n\r\n\t// Build tool schema parameters\r\n\tconst parameters: JSONSchema7 = {\r\n\t\ttype: 'object',\r\n\t\tproperties: {\r\n\t\t\tquery: {\r\n\t\t\t\ttype: 'string',\r\n\t\t\t\tdescription: 'The search query to find relevant documents',\r\n\t\t\t},\r\n\t\t\tlimit: {\r\n\t\t\t\ttype: 'integer',\r\n\t\t\t\tdescription: `Maximum number of results to return (default: ${defaultLimit}, max: ${maxLimit})`,\r\n\t\t\t\tminimum: 1,\r\n\t\t\t\tmaximum: maxLimit,\r\n\t\t\t\tdefault: defaultLimit,\r\n\t\t\t},\r\n\t\t\t...extendParameters,\r\n\t\t},\r\n\t\trequired: ['query'],\r\n\t}\r\n\r\n\tconst schema: ToolSchema = {\r\n\t\tname,\r\n\t\tdescription,\r\n\t\tparameters,\r\n\t}\r\n\r\n\tasync function handler(\r\n\t\targs: Readonly<Record<string, unknown>>,\r\n\t): Promise<readonly unknown[]> {\r\n\t\tconst query = args.query\r\n\t\tif (typeof query !== 'string' || query.length === 0) {\r\n\t\t\treturn []\r\n\t\t}\r\n\r\n\t\tconst requestedLimit = args.limit\r\n\t\tlet limit = defaultLimit\r\n\t\tif (typeof requestedLimit === 'number' && Number.isInteger(requestedLimit)) {\r\n\t\t\tlimit = Math.min(Math.max(1, requestedLimit), maxLimit)\r\n\t\t}\r\n\r\n\t\t// Build filter if provided\r\n\t\tconst filter = buildFilter?.(args)\r\n\r\n\t\t// Search vectorstore - only include filter if defined\r\n\t\tconst searchOptions = filter !== undefined\r\n\t\t\t? { limit, filter }\r\n\t\t\t: { limit }\r\n\t\tconst results = await vectorStore.search(query, searchOptions)\r\n\r\n\t\t// Filter by score threshold\r\n\t\tlet filteredResults = results\r\n\t\tif (scoreThreshold !== undefined) {\r\n\t\t\tfilteredResults = results.filter(r => r.score >= scoreThreshold)\r\n\t\t}\r\n\r\n\t\t// Format results\r\n\t\treturn filteredResults.map(formatResult)\r\n\t}\r\n\r\n\treturn { schema, handler }\r\n}\r\n\r\n/**\r\n * Default result formatter - returns content and metadata.\r\n */\r\nfunction defaultFormatResult(result: ScoredResult): unknown {\r\n\treturn {\r\n\t\tcontent: result.content,\r\n\t\tscore: result.score,\r\n\t\tmetadata: result.metadata,\r\n\t}\r\n}\r\n","/**\r\n * @mikesaintsg/core\r\n *\r\n * Form dirty guard that prevents navigation when form has unsaved changes.\r\n */\r\n\r\nimport type {\r\n\tFormDirtyGuardOptions,\r\n\tNavigationGuard,\r\n} from '../types.js'\r\nimport { FORM_DIRTY_DEFAULT_MESSAGE } from '../constants.js'\r\n\r\n/**\r\n * Create a navigation guard that prevents leaving when form is dirty.\r\n *\r\n * @param options - Form dirty guard configuration options\r\n * @returns A navigation guard function\r\n *\r\n * @example\r\n * ```ts\r\n * import { createForm } from '@mikesaintsg/form'\r\n * import { createFormDirtyGuard } from '@mikesaintsg/core'\r\n *\r\n * const form = createForm({ ... })\r\n *\r\n * const guard = createFormDirtyGuard({\r\n *   form,\r\n *   confirmFn: (message) => window.confirm(message),\r\n *   message: 'You have unsaved changes. Continue?',\r\n *   excludePages: ['settings'],\r\n * })\r\n *\r\n * // Use with router\r\n * router.beforeNavigate(guard)\r\n * ```\r\n */\r\nexport function createFormDirtyGuard<TFormData = unknown, TPage extends string = string>(\r\n\toptions: FormDirtyGuardOptions<TFormData, TPage>,\r\n): NavigationGuard<TPage> {\r\n\tconst {\r\n\t\tform,\r\n\t\tconfirmFn,\r\n\t\tmessage = FORM_DIRTY_DEFAULT_MESSAGE,\r\n\t\texcludePages = [],\r\n\t\tonlyFromPages,\r\n\t} = options\r\n\r\n\treturn async function guard(to: TPage, from: TPage): Promise<boolean> {\r\n\t\t// Check if we should skip guard for this navigation\r\n\t\tif (shouldSkipGuard(to, from, excludePages, onlyFromPages)) {\r\n\t\t\treturn true\r\n\t\t}\r\n\r\n\t\t// If form is not dirty, allow navigation\r\n\t\tif (!form.isDirty()) {\r\n\t\t\treturn true\r\n\t\t}\r\n\r\n\t\t// Form is dirty, ask for confirmation\r\n\t\tconst confirmed = await Promise.resolve(confirmFn(message))\r\n\t\treturn confirmed\r\n\t}\r\n}\r\n\r\n/**\r\n * Determine if guard should be skipped for this navigation.\r\n */\r\nfunction shouldSkipGuard<TPage extends string>(\r\n\tto: TPage,\r\n\tfrom: TPage,\r\n\texcludePages: readonly TPage[],\r\n\tonlyFromPages: readonly TPage[] | undefined,\r\n): boolean {\r\n\t// Skip if navigating to excluded page\r\n\tif (excludePages.includes(to)) {\r\n\t\treturn true\r\n\t}\r\n\r\n\t// Skip if from page is not in onlyFromPages (if specified)\r\n\tif (onlyFromPages !== undefined && !onlyFromPages.includes(from)) {\r\n\t\treturn true\r\n\t}\r\n\r\n\treturn false\r\n}\r\n","/**\r\n * @mikesaintsg/core\r\n *\r\n * Session persistence bridge that connects inference sessions to IndexedDB storage.\r\n */\r\n\r\nimport type {\r\n\tSessionPersistenceOptions,\r\n\tSessionPersistenceInterface,\r\n\tSerializableSession,\r\n\tSerializedSession,\r\n} from '../types.js'\r\n\r\n/**\r\n * Create a session persistence adapter for storing inference sessions.\r\n *\r\n * @param options - Session persistence configuration options\r\n * @returns A session persistence instance\r\n *\r\n * @example\r\n * ```ts\r\n * import { createDatabase } from '@mikesaintsg/indexeddb'\r\n * import { createSessionPersistence } from '@mikesaintsg/core'\r\n *\r\n * const db = await createDatabase({ name: 'sessions' })\r\n * const persistence = createSessionPersistence({\r\n *   database: db,\r\n *   storeName: 'chat_sessions',\r\n *   autoprune: 7 * 24 * 60 * 60 * 1000, // 7 days\r\n * })\r\n *\r\n * // Save session\r\n * await persistence.save('session-1', session)\r\n *\r\n * // Load session\r\n * const savedSession = await persistence.load('session-1')\r\n * ```\r\n */\r\nexport function createSessionPersistence(\r\n\toptions: SessionPersistenceOptions,\r\n): SessionPersistenceInterface {\r\n\tconst {\r\n\t\tdatabase,\r\n\t\tstoreName,\r\n\t\tautoprune,\r\n\t\tonSaveError,\r\n\t} = options\r\n\r\n\tconst store = database.store<SerializedSession>(storeName)\r\n\r\n\t// Auto-prune on creation if configured\r\n\tif (autoprune !== undefined && autoprune > 0) {\r\n\t\tvoid pruneOldSessions(autoprune)\r\n\t}\r\n\r\n\t/**\r\n\t * Prune sessions older than maxAgeMs.\r\n\t */\r\n\tasync function pruneOldSessions(maxAgeMs: number): Promise<number> {\r\n\t\tconst now = Date.now()\r\n\t\tconst cutoff = now - maxAgeMs\r\n\r\n\t\tconst allSessions = await store.all()\r\n\t\tlet prunedCount = 0\r\n\r\n\t\tfor (const session of allSessions) {\r\n\t\t\tif (session.updatedAt < cutoff) {\r\n\t\t\t\tawait store.remove(session.id)\r\n\t\t\t\tprunedCount++\r\n\t\t\t}\r\n\t\t}\r\n\r\n\t\treturn prunedCount\r\n\t}\r\n\r\n\treturn {\r\n\t\tasync save(id: string, session: SerializableSession): Promise<void> {\r\n\t\t\ttry {\r\n\t\t\t\tconst serialized: SerializedSession = {\r\n\t\t\t\t\tid,\r\n\t\t\t\t\tmessages: [...session.getMessages()],\r\n\t\t\t\t\tmetadata: session.getMetadata(),\r\n\t\t\t\t\tupdatedAt: Date.now(),\r\n\t\t\t\t}\r\n\r\n\t\t\t\tawait store.set(serialized, id)\r\n\t\t\t} catch (error) {\r\n\t\t\t\tonSaveError?.(error, id)\r\n\t\t\t\tthrow error\r\n\t\t\t}\r\n\t\t},\r\n\r\n\t\tasync load(id: string): Promise<SerializedSession | undefined> {\r\n\t\t\treturn store.get(id)\r\n\t\t},\r\n\r\n\t\tasync delete(id: string): Promise<void> {\r\n\t\t\tawait store.remove(id)\r\n\t\t},\r\n\r\n\t\tasync list(): Promise<readonly string[]> {\r\n\t\t\tconst allSessions = await store.all()\r\n\t\t\treturn allSessions.map(s => s.id)\r\n\t\t},\r\n\r\n\t\tasync prune(maxAgeMs: number): Promise<number> {\r\n\t\t\treturn pruneOldSessions(maxAgeMs)\r\n\t\t},\r\n\t}\r\n}\r\n"],"names":["EcosystemError","message","cause","isEcosystemError","error","CoreError","code","isCoreError","ok","value","err","isOk","result","isErr","unwrap","defaultValue","unwrapOrThrow","map","fn","mapErr","chain","computeContentHash","text","data","hashBuffer","b","BRIDGE_DEFAULT_TIMEOUT","RETRIEVAL_DEFAULT_LIMIT","RETRIEVAL_MAX_LIMIT","FORM_DIRTY_DEFAULT_MESSAGE","createToolCallBridge","options","registry","timeout","onError","onBeforeExecute","onAfterExecute","executeWithTimeout","toolCall","timeoutPromise","_","reject","errorMessage","toolCalls","name","createRetrievalTool","vectorStore","description","defaultLimit","maxLimit","scoreThreshold","formatResult","defaultFormatResult","extendParameters","buildFilter","parameters","schema","handler","args","query","requestedLimit","limit","filter","searchOptions","results","filteredResults","r","createFormDirtyGuard","form","confirmFn","excludePages","onlyFromPages","to","from","shouldSkipGuard","createSessionPersistence","database","storeName","autoprune","onSaveError","store","pruneOldSessions","maxAgeMs","cutoff","allSessions","prunedCount","session","id","serialized","s"],"mappings":"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"}
+{"version":3,"file":"index.js","sources":["../src/errors.ts","../src/helpers.ts","../src/constants.ts","../src/factories.ts"],"sourcesContent":["/**\n * @mikesaintsg/core\n *\n * Base error class and utilities for the ecosystem.\n */\n// ============================================================================\n// Base Ecosystem Error\n// ============================================================================\n/**\n * Base error class for all ecosystem errors.\n * All package-specific errors should extend this class.\n *\n * @example\n * ```ts\n * class StorageError extends EcosystemError {\n *   readonly code: StorageErrorCode\n *\n *   constructor(code: StorageErrorCode, message: string, cause?: Error) {\n *     super(message, cause)\n *     this.code = code\n *   }\n * }\n * ```\n */\nexport abstract class EcosystemError extends Error {\n\t/** Error code for programmatic handling */\n\tabstract readonly code: string\n\t/** Original error that caused this one */\n\toverride readonly cause: Error | undefined\n\n\tconstructor(message: string, cause?: Error) {\n\t\tsuper(message)\n\t\tthis.name = this.constructor.name\n\t\tthis.cause = cause\n\t}\n}\n/**\n * Type guard for ecosystem errors.\n *\n * @param error - The value to check\n * @returns True if the error is an EcosystemError\n *\n * @example\n * ```ts\n * try {\n *   await someOperation()\n * } catch (error) {\n *   if (isEcosystemError(error)) {\n *     console.log('Code:', error.code)\n *   }\n * }\n * ```\n */\nexport function isEcosystemError(error: unknown): error is EcosystemError {\n\treturn error instanceof EcosystemError\n}\n","/**\r\n * @mikesaintsg/core\r\n *\r\n * Helper functions and type guards.\r\n */\r\n\r\nimport type { Ok, Err, Result, ContentHash, ScoredResult } from './types.js'\r\n\r\n// ============================================================================\r\n// Result Pattern Helpers\r\n// ============================================================================\r\n\r\n/**\r\n * Create a success result.\r\n *\r\n * @param value - The success value\r\n * @returns An Ok result containing the value\r\n *\r\n * @example\r\n * ```ts\r\n * const result = ok(42)\r\n * // result.ok === true\r\n * // result.value === 42\r\n * ```\r\n */\r\nexport function ok<T>(value: T): Ok<T> {\r\n\treturn { ok: true, value }\r\n}\r\n\r\n/**\r\n * Create a failure result.\r\n *\r\n * @param error - The error value\r\n * @returns An Err result containing the error\r\n *\r\n * @example\r\n * ```ts\r\n * const result = err('NOT_FOUND')\r\n * // result.ok === false\r\n * // result.error === 'NOT_FOUND'\r\n * ```\r\n */\r\nexport function err<E>(error: E): Err<E> {\r\n\treturn { ok: false, error }\r\n}\r\n\r\n/**\r\n * Check if a result is a success.\r\n *\r\n * @param result - The result to check\r\n * @returns True if the result is Ok, false otherwise\r\n *\r\n * @example\r\n * ```ts\r\n * const result: Result<number, string> = ok(42)\r\n * if (isOk(result)) {\r\n *   console.log(result.value) // TypeScript knows result is Ok<number>\r\n * }\r\n * ```\r\n */\r\nexport function isOk<T, E>(result: Result<T, E>): result is Ok<T> {\r\n\treturn result.ok === true\r\n}\r\n\r\n/**\r\n * Check if a result is a failure.\r\n *\r\n * @param result - The result to check\r\n * @returns True if the result is Err, false otherwise\r\n *\r\n * @example\r\n * ```ts\r\n * const result: Result<number, string> = err('NOT_FOUND')\r\n * if (isErr(result)) {\r\n *   console.log(result.error) // TypeScript knows result is Err<string>\r\n * }\r\n * ```\r\n */\r\nexport function isErr<T, E>(result: Result<T, E>): result is Err<E> {\r\n\treturn !result.ok\r\n}\r\n\r\n/**\r\n * Unwrap a result, returning the value or a default.\r\n *\r\n * @param result - The result to unwrap\r\n * @param defaultValue - Value to return if result is an error\r\n * @returns The success value or the default value\r\n *\r\n * @example\r\n * ```ts\r\n * const value = unwrap(ok(42), 0) // 42\r\n * const fallback = unwrap(err('oops'), 0) // 0\r\n * ```\r\n */\r\nexport function unwrap<T, E>(result: Result<T, E>, defaultValue: T): T {\r\n\treturn result.ok ? result.value : defaultValue\r\n}\r\n\r\n/**\r\n * Unwrap a result, throwing if it's an error.\r\n *\r\n * @param result - The result to unwrap\r\n * @returns The success value\r\n * @throws The error if result is Err\r\n *\r\n * @example\r\n * ```ts\r\n * const value = unwrapOrThrow(ok(42)) // 42\r\n * unwrapOrThrow(err(new Error('oops'))) // throws Error('oops')\r\n * ```\r\n */\r\nexport function unwrapOrThrow<T, E>(result: Result<T, E>): T {\r\n\tif (result.ok) {\r\n\t\treturn result.value\r\n\t}\r\n\tif (result.error instanceof Error) {\r\n\t\tthrow result.error\r\n\t}\r\n\tthrow new Error(String(result.error))\r\n}\r\n\r\n/**\r\n * Map a function over a success value.\r\n *\r\n * @param result - The result to map over\r\n * @param fn - Function to apply to the success value\r\n * @returns A new result with the mapped value, or the original error\r\n *\r\n * @example\r\n * ```ts\r\n * const doubled = map(ok(5), x => x * 2) // ok(10)\r\n * const failed = map(err('oops'), x => x * 2) // err('oops')\r\n * ```\r\n */\r\nexport function map<T, U, E>(\r\n\tresult: Result<T, E>,\r\n\tfn: (value: T) => U,\r\n): Result<U, E> {\r\n\treturn result.ok ? ok(fn(result.value)) : result\r\n}\r\n\r\n/**\r\n * Map a function over an error value.\r\n *\r\n * @param result - The result to map over\r\n * @param fn - Function to apply to the error value\r\n * @returns A new result with the mapped error, or the original value\r\n *\r\n * @example\r\n * ```ts\r\n * const wrapped = mapErr(err('oops'), e => new Error(e)) // err(Error('oops'))\r\n * const unchanged = mapErr(ok(42), e => new Error(e)) // ok(42)\r\n * ```\r\n */\r\nexport function mapErr<T, E, F>(\r\n\tresult: Result<T, E>,\r\n\tfn: (error: E) => F,\r\n): Result<T, F> {\r\n\treturn result.ok ? result : err(fn(result.error))\r\n}\r\n\r\n/**\r\n * Chain results (flatMap). Apply a function that returns a Result to a success value.\r\n *\r\n * @param result - The result to chain\r\n * @param fn - Function returning a new Result\r\n * @returns The result of applying fn, or the original error\r\n *\r\n * @example\r\n * ```ts\r\n * const parsed = chain(ok('42'), s => {\r\n *   const n = parseInt(s, 10)\r\n *   return isNaN(n) ? err('PARSE_ERROR') : ok(n)\r\n * })\r\n * // parsed = ok(42)\r\n * ```\r\n */\r\nexport function chain<T, U, E>(\r\n\tresult: Result<T, E>,\r\n\tfn: (value: T) => Result<U, E>,\r\n): Result<U, E> {\r\n\treturn result.ok ? fn(result.value) : result\r\n}\r\n\r\n// ============================================================================\r\n// Content Hashing Helpers\r\n// ============================================================================\r\n\r\n/**\r\n * Compute a SHA-256 content hash for text.\r\n *\r\n * @param text - The text to hash\r\n * @returns A hex string content hash\r\n *\r\n * @example\r\n * ```ts\r\n * const hash = await computeContentHash('Hello, world!')\r\n * // hash = 'a591a6d40bf420404a011733cfb7b190d62c65bf0bcda32b57b277d9ad9f146e'\r\n * ```\r\n */\r\nexport async function computeContentHash(text: string): Promise<ContentHash> {\r\n\tconst encoder = new TextEncoder()\r\n\tconst data = encoder.encode(text)\r\n\tconst hashBuffer = await crypto.subtle.digest('SHA-256', data)\r\n\tconst hashArray = Array.from(new Uint8Array(hashBuffer))\r\n\treturn hashArray.map(b => b.toString(16).padStart(2, '0')).join('')\r\n}\r\n\r\n// ============================================================================\r\n// Bridge Helpers\r\n// ============================================================================\r\n\r\n/**\r\n * Check if a value is a single ToolCall (not an array).\r\n *\r\n * @param value - Value to check\r\n * @returns True if the value is a single ToolCall\r\n */\r\nexport function isToolCall(value: unknown): value is { id: string; name: string; arguments: unknown } {\r\n\treturn (\r\n\t\ttypeof value === 'object' &&\r\n\t\tvalue !== null &&\r\n\t\t'id' in value &&\r\n\t\t'name' in value &&\r\n\t\t'arguments' in value\r\n\t)\r\n}\r\n\r\n/**\r\n * Determine if form dirty guard should be skipped for a navigation.\r\n *\r\n * @param to - Target page\r\n * @param from - Source page\r\n * @param excludePages - Pages to exclude from guard\r\n * @param onlyFromPages - Only guard from these pages (if specified)\r\n * @returns True if guard should be skipped\r\n */\r\nexport function shouldSkipFormGuard<TPage extends string>(\r\n\tto: TPage,\r\n\tfrom: TPage,\r\n\texcludePages: readonly TPage[],\r\n\tonlyFromPages: readonly TPage[] | undefined,\r\n): boolean {\r\n\t// Skip if navigating to excluded page\r\n\tif (excludePages.includes(to)) {\r\n\t\treturn true\r\n\t}\r\n\r\n\t// Skip if from page is not in onlyFromPages (if specified)\r\n\tif (onlyFromPages !== undefined && !onlyFromPages.includes(from)) {\r\n\t\treturn true\r\n\t}\r\n\r\n\treturn false\r\n}\r\n\r\n/**\r\n * Default result formatter for retrieval tools.\r\n * Returns content, score, and metadata.\r\n *\r\n * @param result - Scored result to format\r\n * @returns Formatted result object\r\n */\r\nexport function formatScoredResult(result: ScoredResult): unknown {\r\n\treturn {\r\n\t\tcontent: result.content,\r\n\t\tscore: result.score,\r\n\t\tmetadata: result.metadata,\r\n\t}\r\n}\r\n","/**\r\n * @mikesaintsg/core\r\n *\r\n * Shared constants for the core library.\r\n */\r\n\r\n// ============================================================================\r\n// Bridge Constants\r\n// ============================================================================\r\n\r\n/** Default timeout for bridge operations in milliseconds */\r\nexport const BRIDGE_DEFAULT_TIMEOUT = 30000\r\n\r\n/** Default retrieval limit for retrieval tool */\r\nexport const RETRIEVAL_DEFAULT_LIMIT = 10\r\n\r\n/** Maximum retrieval limit for retrieval tool */\r\nexport const RETRIEVAL_MAX_LIMIT = 100\r\n\r\n/** Default form dirty guard message */\r\nexport const FORM_DIRTY_DEFAULT_MESSAGE = 'You have unsaved changes. Are you sure you want to leave?'\r\n","/**\n * @mikesaintsg/core\n *\n * Factory functions for creating bridge instances.\n */\n\nimport type {\n\tToolCall,\n\tToolResult,\n\tToolCallBridgeOptions,\n\tToolCallBridgeInterface,\n\tRetrievalToolOptions,\n\tRetrievalToolCreated,\n\tToolSchema,\n\tJSONSchema7,\n\tFormDirtyGuardOptions,\n\tNavigationGuard,\n\tSessionPersistenceOptions,\n\tSessionPersistenceInterface,\n\tSerializableSession,\n\tSerializedSession,\n} from './types.js'\nimport {\n\tBRIDGE_DEFAULT_TIMEOUT,\n\tRETRIEVAL_DEFAULT_LIMIT,\n\tRETRIEVAL_MAX_LIMIT,\n\tFORM_DIRTY_DEFAULT_MESSAGE,\n} from './constants.js'\nimport {\n\tisToolCall,\n\tshouldSkipFormGuard,\n\tformatScoredResult,\n} from './helpers.js'\n\n// ============================================================================\n// Tool Call Bridge Factory\n// ============================================================================\n\n/**\n * Create a tool call bridge.\n *\n * @param options - Bridge configuration options\n * @returns A tool call bridge instance\n *\n * @example\n * ```ts\n * import { createToolRegistry } from '@mikesaintsg/contextprotocol'\n * import { createToolCallBridge } from '@mikesaintsg/core'\n *\n * const registry = createToolRegistry()\n * registry.register(weatherTool)\n *\n * const bridge = createToolCallBridge({\n *   registry,\n *   timeout: 30000,\n *   onError: (error, toolCall) => console.error(`Tool ${toolCall.name} failed:`, error),\n * })\n *\n * // Execute tool calls from LLM response\n * const results = await bridge.execute(response.toolCalls)\n * ```\n */\nexport function createToolCallBridge(\n\toptions: ToolCallBridgeOptions,\n): ToolCallBridgeInterface {\n\tconst {\n\t\tregistry,\n\t\ttimeout = BRIDGE_DEFAULT_TIMEOUT,\n\t\tonError,\n\t\tonBeforeExecute,\n\t\tonAfterExecute,\n\t} = options\n\n\tasync function executeWithTimeout(toolCall: ToolCall): Promise<ToolResult> {\n\t\t// Check if tool exists\n\t\tif (!registry.has(toolCall.name)) {\n\t\t\treturn {\n\t\t\t\tcallId: toolCall.id,\n\t\t\t\tname: toolCall.name,\n\t\t\t\tsuccess: false,\n\t\t\t\terror: `Tool not found: ${toolCall.name}`,\n\t\t\t}\n\t\t}\n\n\t\t// Call lifecycle hook\n\t\tonBeforeExecute?.(toolCall)\n\n\t\ttry {\n\t\t\t// Create timeout promise\n\t\t\tconst timeoutPromise = new Promise<never>((_, reject) => {\n\t\t\t\tsetTimeout(() => {\n\t\t\t\t\treject(new Error(`Tool execution timed out after ${timeout}ms`))\n\t\t\t\t}, timeout)\n\t\t\t})\n\n\t\t\t// Execute tool with timeout\n\t\t\tconst value = await Promise.race([\n\t\t\t\tregistry.execute(toolCall.name, toolCall.arguments),\n\t\t\t\ttimeoutPromise,\n\t\t\t])\n\n\t\t\t// Call lifecycle hook\n\t\t\tonAfterExecute?.(toolCall, value)\n\n\t\t\treturn {\n\t\t\t\tcallId: toolCall.id,\n\t\t\t\tname: toolCall.name,\n\t\t\t\tsuccess: true,\n\t\t\t\tvalue,\n\t\t\t}\n\t\t} catch (error) {\n\t\t\t// Call error hook\n\t\t\tonError?.(error, toolCall)\n\n\t\t\tconst errorMessage = error instanceof Error\n\t\t\t\t? error.message\n\t\t\t\t: String(error)\n\n\t\t\treturn {\n\t\t\t\tcallId: toolCall.id,\n\t\t\t\tname: toolCall.name,\n\t\t\t\tsuccess: false,\n\t\t\t\terror: errorMessage,\n\t\t\t}\n\t\t}\n\t}\n\n\treturn {\n\t\texecute(toolCallOrCalls: ToolCall | readonly ToolCall[]) {\n\t\t\tif (isToolCall(toolCallOrCalls)) {\n\t\t\t\treturn executeWithTimeout(toolCallOrCalls)\n\t\t\t}\n\t\t\treturn Promise.all(\n\t\t\t\t(toolCallOrCalls).map(tc => executeWithTimeout(tc)),\n\t\t\t)\n\t\t},\n\n\t\thasTool(name: string): boolean {\n\t\t\treturn registry.has(name)\n\t\t},\n\t} as ToolCallBridgeInterface\n}\n\n// ============================================================================\n// Retrieval Tool Factory\n// ============================================================================\n\n/**\n * Create a retrieval tool for use with contextprotocol tool registry.\n *\n * @param options - Retrieval tool configuration options\n * @returns A tool schema and handler for registration\n *\n * @example\n * ```ts\n * import { createVectorStore } from '@mikesaintsg/vectorstore'\n * import { createToolRegistry } from '@mikesaintsg/contextprotocol'\n * import { createRetrievalTool } from '@mikesaintsg/core'\n *\n * const vectorStore = createVectorStore({ ... })\n * const registry = createToolRegistry()\n *\n * const { schema, handler } = createRetrievalTool({\n *   vectorStore,\n *   name: 'search_docs',\n *   description: 'Search documentation for relevant information',\n *   defaultLimit: 5,\n *   scoreThreshold: 0.7,\n * })\n *\n * registry.register({ ...schema, execute: handler })\n * ```\n */\nexport function createRetrievalTool<TMetadata = unknown>(\n\toptions: RetrievalToolOptions<TMetadata>,\n): RetrievalToolCreated {\n\tconst {\n\t\tvectorStore,\n\t\tname,\n\t\tdescription,\n\t\tdefaultLimit = RETRIEVAL_DEFAULT_LIMIT,\n\t\tmaxLimit = RETRIEVAL_MAX_LIMIT,\n\t\tscoreThreshold,\n\t\tformatResult = formatScoredResult,\n\t\textendParameters = {},\n\t\tbuildFilter,\n\t} = options\n\n\t// Build tool schema parameters\n\tconst parameters: JSONSchema7 = {\n\t\ttype: 'object',\n\t\tproperties: {\n\t\t\tquery: {\n\t\t\t\ttype: 'string',\n\t\t\t\tdescription: 'The search query to find relevant documents',\n\t\t\t},\n\t\t\tlimit: {\n\t\t\t\ttype: 'integer',\n\t\t\t\tdescription: `Maximum number of results to return (default: ${defaultLimit}, max: ${maxLimit})`,\n\t\t\t\tminimum: 1,\n\t\t\t\tmaximum: maxLimit,\n\t\t\t\tdefault: defaultLimit,\n\t\t\t},\n\t\t\t...extendParameters,\n\t\t},\n\t\trequired: ['query'],\n\t}\n\n\tconst schema: ToolSchema = {\n\t\tname,\n\t\tdescription,\n\t\tparameters,\n\t}\n\n\tasync function handler(\n\t\targs: Readonly<Record<string, unknown>>,\n\t): Promise<readonly unknown[]> {\n\t\tconst query = args.query\n\t\tif (typeof query !== 'string' || query.length === 0) {\n\t\t\treturn []\n\t\t}\n\n\t\tconst requestedLimit = args.limit\n\t\tlet limit = defaultLimit\n\t\tif (typeof requestedLimit === 'number' && Number.isInteger(requestedLimit)) {\n\t\t\tlimit = Math.min(Math.max(1, requestedLimit), maxLimit)\n\t\t}\n\n\t\t// Build filter if provided\n\t\tconst filter = buildFilter?.(args)\n\n\t\t// Search vectorstore - only include filter if defined\n\t\tconst searchOptions = filter !== undefined\n\t\t\t? { limit, filter }\n\t\t\t: { limit }\n\t\tconst results = await vectorStore.search(query, searchOptions)\n\n\t\t// Filter by score threshold\n\t\tlet filteredResults = results\n\t\tif (scoreThreshold !== undefined) {\n\t\t\tfilteredResults = results.filter(r => r.score >= scoreThreshold)\n\t\t}\n\n\t\t// Format results\n\t\treturn filteredResults.map(formatResult)\n\t}\n\n\treturn { schema, handler }\n}\n\n// ============================================================================\n// Form Dirty Guard Factory\n// ============================================================================\n\n/**\n * Create a navigation guard that prevents leaving when form is dirty.\n *\n * @param options - Form dirty guard configuration options\n * @returns A navigation guard function\n *\n * @example\n * ```ts\n * import { createForm } from '@mikesaintsg/form'\n * import { createFormDirtyGuard } from '@mikesaintsg/core'\n *\n * const form = createForm({ ... })\n *\n * const guard = createFormDirtyGuard({\n *   form,\n *   confirmFn: (message) => window.confirm(message),\n *   message: 'You have unsaved changes. Continue?',\n *   excludePages: ['settings'],\n * })\n *\n * // Use with router\n * router.beforeNavigate(guard)\n * ```\n */\nexport function createFormDirtyGuard<TFormData = unknown, TPage extends string = string>(\n\toptions: FormDirtyGuardOptions<TFormData, TPage>,\n): NavigationGuard<TPage> {\n\tconst {\n\t\tform,\n\t\tconfirmFn,\n\t\tmessage = FORM_DIRTY_DEFAULT_MESSAGE,\n\t\texcludePages = [],\n\t\tonlyFromPages,\n\t} = options\n\n\treturn async function guard(to: TPage, from: TPage): Promise<boolean> {\n\t\t// Check if we should skip guard for this navigation\n\t\tif (shouldSkipFormGuard(to, from, excludePages, onlyFromPages)) {\n\t\t\treturn true\n\t\t}\n\n\t\t// If form is not dirty, allow navigation\n\t\tif (!form.isDirty()) {\n\t\t\treturn true\n\t\t}\n\n\t\t// Form is dirty, ask for confirmation\n\t\treturn Promise.resolve(confirmFn(message))\n\t}\n}\n\n// ============================================================================\n// Session Persistence Factory\n// ============================================================================\n\n/**\n * Create a session persistence adapter for storing inference sessions.\n *\n * @param options - Session persistence configuration options\n * @returns A session persistence instance\n *\n * @example\n * ```ts\n * import { createDatabase } from '@mikesaintsg/indexeddb'\n * import { createSessionPersistence } from '@mikesaintsg/core'\n *\n * const db = await createDatabase({ name: 'sessions' })\n * const persistence = createSessionPersistence({\n *   database: db,\n *   storeName: 'chat_sessions',\n *   autoprune: 7 * 24 * 60 * 60 * 1000, // 7 days\n * })\n *\n * // Save session\n * await persistence.save('session-1', session)\n *\n * // Load session\n * const savedSession = await persistence.load('session-1')\n * ```\n */\nexport function createSessionPersistence(\n\toptions: SessionPersistenceOptions,\n): SessionPersistenceInterface {\n\tconst {\n\t\tdatabase,\n\t\tstoreName,\n\t\tautoprune,\n\t\tonSaveError,\n\t} = options\n\n\tconst store = database.store<SerializedSession>(storeName)\n\n\tasync function pruneOldSessions(maxAgeMs: number): Promise<number> {\n\t\tconst now = Date.now()\n\t\tconst cutoff = now - maxAgeMs\n\n\t\tconst allSessions = await store.all()\n\t\tlet prunedCount = 0\n\n\t\tfor (const session of allSessions) {\n\t\t\tif (session.updatedAt < cutoff) {\n\t\t\t\tawait store.remove(session.id)\n\t\t\t\tprunedCount++\n\t\t\t}\n\t\t}\n\n\t\treturn prunedCount\n\t}\n\n\t// Auto-prune on creation if configured\n\tif (autoprune !== undefined && autoprune > 0) {\n\t\tvoid pruneOldSessions(autoprune)\n\t}\n\n\treturn {\n\t\tasync save(id: string, session: SerializableSession): Promise<void> {\n\t\t\ttry {\n\t\t\t\tconst serialized: SerializedSession = {\n\t\t\t\t\tid,\n\t\t\t\t\tmessages: [...session.getMessages()],\n\t\t\t\t\tmetadata: session.getMetadata(),\n\t\t\t\t\tupdatedAt: Date.now(),\n\t\t\t\t}\n\n\t\t\t\tawait store.set(serialized, id)\n\t\t\t} catch (error) {\n\t\t\t\tonSaveError?.(error, id)\n\t\t\t\tthrow error\n\t\t\t}\n\t\t},\n\n\t\tasync load(id: string): Promise<SerializedSession | undefined> {\n\t\t\treturn store.get(id)\n\t\t},\n\n\t\tasync delete(id: string): Promise<void> {\n\t\t\tawait store.remove(id)\n\t\t},\n\n\t\tasync list(): Promise<readonly string[]> {\n\t\t\tconst allSessions = await store.all()\n\t\t\treturn allSessions.map(s => s.id)\n\t\t},\n\n\t\tasync prune(maxAgeMs: number): Promise<number> {\n\t\t\treturn pruneOldSessions(maxAgeMs)\n\t\t},\n\t}\n}\n"],"names":["EcosystemError","message","cause","isEcosystemError","error","ok","value","err","isOk","result","isErr","unwrap","defaultValue","unwrapOrThrow","map","fn","mapErr","chain","computeContentHash","text","data","hashBuffer","b","isToolCall","shouldSkipFormGuard","to","from","excludePages","onlyFromPages","formatScoredResult","BRIDGE_DEFAULT_TIMEOUT","RETRIEVAL_DEFAULT_LIMIT","RETRIEVAL_MAX_LIMIT","FORM_DIRTY_DEFAULT_MESSAGE","createToolCallBridge","options","registry","timeout","onError","onBeforeExecute","onAfterExecute","executeWithTimeout","toolCall","timeoutPromise","_","reject","errorMessage","toolCallOrCalls","tc","name","createRetrievalTool","vectorStore","description","defaultLimit","maxLimit","scoreThreshold","formatResult","extendParameters","buildFilter","parameters","schema","handler","args","query","requestedLimit","limit","filter","searchOptions","results","filteredResults","r","createFormDirtyGuard","form","confirmFn","createSessionPersistence","database","storeName","autoprune","onSaveError","store","pruneOldSessions","maxAgeMs","cutoff","allSessions","prunedCount","session","id","serialized","s"],"mappings":"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"}

package/package.json

@@ -1,6 +1,6 @@
 {
 	"name": "@mikesaintsg/core",
-	"version": "0.0.2",
+	"version": "0.0.3",
 	"type": "module",
 	"description": "Type-safe FileSystem wrapper with full TypeScript support. Zero runtime dependencies.",
 	"keywords": [