mcard-js 2.1.12 → 2.1.13

package/dist/rag/semanticVersioning.d.ts

@@ -0,0 +1,187 @@
+/**
+ * Semantic Versioning API for MCards
+ *
+ * High-level API functions for managing MCard versions linked to handles
+ * with semantic similarity detection.
+ *
+ * This module provides a simplified interface for:
+ * - Linking MCards to handles
+ * - Retrieving version history with semantic info
+ * - Comparing versions by semantic similarity
+ * - Searching within a handle's version history
+ *
+ * @module mcard-js/rag/semanticVersioning
+ */
+import { MCard } from '../model/MCard';
+import { HandleVectorStore, VersionSimilarityResult, VectorStoreConfig } from './HandleVectorStore';
+/**
+ * Get the default HandleVectorStore instance.
+ *
+ * @param dbPath Path to SQLite database (undefined = in-memory)
+ * @param config RAG configuration
+ * @param reinitialize Force re-initialization of the store
+ * @returns HandleVectorStore instance
+ */
+export declare function getStore(dbPath?: string, config?: Partial<VectorStoreConfig>, reinitialize?: boolean): HandleVectorStore;
+/**
+ * Reset the default store (useful for testing).
+ */
+export declare function resetStore(): void;
+/**
+ * Link an MCard to a handle with semantic embedding.
+ *
+ * This function:
+ * 1. Indexes the MCard content with vector embeddings
+ * 2. Associates the MCard with the specified handle
+ * 3. Computes semantic delta from previous version (if exists)
+ * 4. Classifies the upgrade type based on similarity
+ *
+ * @param mcard MCard to link
+ * @param handle Handle name (stable identifier)
+ * @param isCurrent Whether this becomes the current version
+ * @param store Optional custom HandleVectorStore instance
+ * @returns True if successful, false if indexing failed
+ *
+ * @example
+ * ```typescript
+ * import { MCard } from 'mcard-js';
+ * import { linkMCardToHandle } from 'mcard-js/rag';
+ *
+ * const doc = await MCard.create('Introduction to Machine Learning...');
+ * await linkMCardToHandle(doc, 'ml_intro');
+ * ```
+ */
+export declare function linkMCardToHandle(mcard: MCard, handle: string, isCurrent?: boolean, store?: HandleVectorStore): Promise<boolean>;
+/**
+ * Get version history for a handle with semantic info.
+ *
+ * @param handle Handle name to query
+ * @param store Optional custom HandleVectorStore instance
+ * @returns List of version objects with hash, order, timestamps, embedding status, and upgrade type
+ *
+ * @example
+ * ```typescript
+ * const history = getHandleVersionHistory('ml_intro');
+ * for (const v of history) {
+ *     console.log(`v${v.versionOrder}: ${v.hash.slice(0, 8)} (${v.upgradeType})`);
+ * }
+ * ```
+ */
+export declare function getHandleVersionHistory(handle: string, store?: HandleVectorStore): Array<{
+    hash: string;
+    versionOrder: number;
+    isCurrent: boolean;
+    createdAt: string;
+    hasEmbedding: boolean;
+    parentHash?: string;
+    semanticDelta?: number;
+    upgradeType?: string;
+}>;
+/**
+ * Compare all versions of a handle by semantic similarity.
+ *
+ * This is useful for:
+ * - Understanding how content has evolved
+ * - Finding which version is most similar to current
+ * - Identifying major semantic drift points
+ *
+ * @param handle Handle name
+ * @param referenceHash Compare to this hash (default: current version)
+ * @param metric 'cosine' (higher = more similar) or 'euclidean' (lower = closer)
+ * @param store Optional custom HandleVectorStore instance
+ * @returns Versions sorted by similarity to reference
+ *
+ * @example
+ * ```typescript
+ * const results = compareVersionsBySimilarity('ml_intro');
+ * for (const r of results) {
+ *     console.log(`v${r.versionOrder}: sim=${r.similarityToCurrent.toFixed(4)}`);
+ * }
+ * ```
+ */
+export declare function compareVersionsBySimilarity(handle: string, referenceHash?: string, metric?: 'cosine' | 'euclidean', store?: HandleVectorStore): VersionSimilarityResult[];
+/**
+ * Search semantically within a handle's version history.
+ *
+ * Useful for finding which version of a document best matches
+ * a specific concept, topic, or query.
+ *
+ * @param handle Handle name to filter by
+ * @param query Search query text
+ * @param k Number of results to return
+ * @param store Optional custom HandleVectorStore instance
+ * @returns Matching versions sorted by query similarity
+ *
+ * @example
+ * ```typescript
+ * const results = await searchWithinHandle('ml_intro', 'neural networks');
+ * for (const r of results) {
+ *     console.log(`v${r.versionOrder}: query_sim=${r.similarityToQuery?.toFixed(4)}`);
+ * }
+ * ```
+ */
+export declare function searchWithinHandle(handle: string, query: string, k?: number, store?: HandleVectorStore): Promise<VersionSimilarityResult[]>;
+/**
+ * Compute pairwise semantic distances between all versions.
+ *
+ * Returns a Map mapping "hash_a:hash_b" string keys to their cosine similarity scores.
+ *
+ * @param handle Handle name
+ * @param cache Whether to cache computed similarities
+ * @param store Optional custom HandleVectorStore instance
+ * @returns Map of hash pair keys to cosine similarity [-1, 1]
+ *
+ * @example
+ * ```typescript
+ * const distances = getVersionDistances('ml_intro');
+ * distances.forEach((sim, key) => {
+ *     console.log(`${key}: ${sim.toFixed(4)}`);
+ * });
+ * ```
+ */
+export declare function getVersionDistances(handle: string, cache?: boolean, store?: HandleVectorStore): Map<string, number>;
+/**
+ * Find the version most similar to a query.
+ *
+ * @param handle Handle name
+ * @param query Search query text
+ * @param store Optional custom HandleVectorStore instance
+ * @returns Most similar version, or undefined if no versions exist
+ */
+export declare function findMostSimilarVersion(handle: string, query: string, store?: HandleVectorStore): Promise<VersionSimilarityResult | undefined>;
+/**
+ * Get the semantic evolution of a handle's versions.
+ *
+ * Returns version history annotated with semantic deltas,
+ * showing how content has evolved over time.
+ *
+ * @param handle Handle name
+ * @param store Optional custom HandleVectorStore instance
+ * @returns List of version objects with evolution info
+ */
+export declare function getSemanticEvolution(handle: string, store?: HandleVectorStore): Array<{
+    hash: string;
+    version: number;
+    isCurrent: boolean;
+    createdAt: string;
+    parentHash?: string;
+    semanticDelta?: number;
+    upgradeType?: string;
+    interpretation: string;
+}>;
+/**
+ * List all handles with indexed versions.
+ *
+ * @param store Optional custom HandleVectorStore instance
+ * @returns List of handle names
+ */
+export declare function listHandles(store?: HandleVectorStore): string[];
+/**
+ * Get information about the vector store.
+ *
+ * @param store Optional custom HandleVectorStore instance
+ * @returns Object with store statistics
+ */
+export declare function getStoreInfo(store?: HandleVectorStore): Record<string, unknown>;
+export { HandleVersion, VersionSimilarityResult } from './HandleVectorStore';
+//# sourceMappingURL=semanticVersioning.d.ts.map

package/dist/rag/semanticVersioning.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"semanticVersioning.d.ts","sourceRoot":"","sources":["../../src/rag/semanticVersioning.ts"],"names":[],"mappings":"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"}

package/dist/rag/semanticVersioning.js

@@ -0,0 +1,253 @@
+/**
+ * Semantic Versioning API for MCards
+ *
+ * High-level API functions for managing MCard versions linked to handles
+ * with semantic similarity detection.
+ *
+ * This module provides a simplified interface for:
+ * - Linking MCards to handles
+ * - Retrieving version history with semantic info
+ * - Comparing versions by semantic similarity
+ * - Searching within a handle's version history
+ *
+ * @module mcard-js/rag/semanticVersioning
+ */
+import { HandleVectorStore } from './HandleVectorStore';
+// Default store instance (lazy-initialized)
+let _defaultStore = null;
+/**
+ * Get the default HandleVectorStore instance.
+ *
+ * @param dbPath Path to SQLite database (undefined = in-memory)
+ * @param config RAG configuration
+ * @param reinitialize Force re-initialization of the store
+ * @returns HandleVectorStore instance
+ */
+export function getStore(dbPath, config, reinitialize = false) {
+    if (_defaultStore === null || reinitialize) {
+        _defaultStore = new HandleVectorStore(dbPath ?? ':memory:', config);
+    }
+    return _defaultStore;
+}
+/**
+ * Reset the default store (useful for testing).
+ */
+export function resetStore() {
+    if (_defaultStore) {
+        _defaultStore.close();
+        _defaultStore = null;
+    }
+}
+// ─────────────────────────────────────────────────────────────────────────────
+// Core API Functions
+// ─────────────────────────────────────────────────────────────────────────────
+/**
+ * Link an MCard to a handle with semantic embedding.
+ *
+ * This function:
+ * 1. Indexes the MCard content with vector embeddings
+ * 2. Associates the MCard with the specified handle
+ * 3. Computes semantic delta from previous version (if exists)
+ * 4. Classifies the upgrade type based on similarity
+ *
+ * @param mcard MCard to link
+ * @param handle Handle name (stable identifier)
+ * @param isCurrent Whether this becomes the current version
+ * @param store Optional custom HandleVectorStore instance
+ * @returns True if successful, false if indexing failed
+ *
+ * @example
+ * ```typescript
+ * import { MCard } from 'mcard-js';
+ * import { linkMCardToHandle } from 'mcard-js/rag';
+ *
+ * const doc = await MCard.create('Introduction to Machine Learning...');
+ * await linkMCardToHandle(doc, 'ml_intro');
+ * ```
+ */
+export async function linkMCardToHandle(mcard, handle, isCurrent = true, store) {
+    const s = store ?? getStore();
+    const indexed = await s.indexWithHandle(mcard, handle, isCurrent);
+    return indexed > 0;
+}
+/**
+ * Get version history for a handle with semantic info.
+ *
+ * @param handle Handle name to query
+ * @param store Optional custom HandleVectorStore instance
+ * @returns List of version objects with hash, order, timestamps, embedding status, and upgrade type
+ *
+ * @example
+ * ```typescript
+ * const history = getHandleVersionHistory('ml_intro');
+ * for (const v of history) {
+ *     console.log(`v${v.versionOrder}: ${v.hash.slice(0, 8)} (${v.upgradeType})`);
+ * }
+ * ```
+ */
+export function getHandleVersionHistory(handle, store) {
+    const s = store ?? getStore();
+    const versions = s.getHandleVersions(handle);
+    return versions.map(v => ({
+        hash: v.hash,
+        versionOrder: v.versionOrder,
+        isCurrent: v.isCurrent,
+        createdAt: v.createdAt,
+        hasEmbedding: v.embeddingId !== undefined,
+        parentHash: v.parentHash,
+        semanticDelta: v.semanticDelta,
+        upgradeType: v.upgradeType,
+    }));
+}
+/**
+ * Compare all versions of a handle by semantic similarity.
+ *
+ * This is useful for:
+ * - Understanding how content has evolved
+ * - Finding which version is most similar to current
+ * - Identifying major semantic drift points
+ *
+ * @param handle Handle name
+ * @param referenceHash Compare to this hash (default: current version)
+ * @param metric 'cosine' (higher = more similar) or 'euclidean' (lower = closer)
+ * @param store Optional custom HandleVectorStore instance
+ * @returns Versions sorted by similarity to reference
+ *
+ * @example
+ * ```typescript
+ * const results = compareVersionsBySimilarity('ml_intro');
+ * for (const r of results) {
+ *     console.log(`v${r.versionOrder}: sim=${r.similarityToCurrent.toFixed(4)}`);
+ * }
+ * ```
+ */
+export function compareVersionsBySimilarity(handle, referenceHash, metric = 'cosine', store) {
+    const s = store ?? getStore();
+    return s.getVersionsBySimilarity(handle, referenceHash, metric);
+}
+/**
+ * Search semantically within a handle's version history.
+ *
+ * Useful for finding which version of a document best matches
+ * a specific concept, topic, or query.
+ *
+ * @param handle Handle name to filter by
+ * @param query Search query text
+ * @param k Number of results to return
+ * @param store Optional custom HandleVectorStore instance
+ * @returns Matching versions sorted by query similarity
+ *
+ * @example
+ * ```typescript
+ * const results = await searchWithinHandle('ml_intro', 'neural networks');
+ * for (const r of results) {
+ *     console.log(`v${r.versionOrder}: query_sim=${r.similarityToQuery?.toFixed(4)}`);
+ * }
+ * ```
+ */
+export async function searchWithinHandle(handle, query, k = 10, store) {
+    const s = store ?? getStore();
+    return s.searchHandleVersions(handle, query, k);
+}
+/**
+ * Compute pairwise semantic distances between all versions.
+ *
+ * Returns a Map mapping "hash_a:hash_b" string keys to their cosine similarity scores.
+ *
+ * @param handle Handle name
+ * @param cache Whether to cache computed similarities
+ * @param store Optional custom HandleVectorStore instance
+ * @returns Map of hash pair keys to cosine similarity [-1, 1]
+ *
+ * @example
+ * ```typescript
+ * const distances = getVersionDistances('ml_intro');
+ * distances.forEach((sim, key) => {
+ *     console.log(`${key}: ${sim.toFixed(4)}`);
+ * });
+ * ```
+ */
+export function getVersionDistances(handle, cache = true, store) {
+    const s = store ?? getStore();
+    return s.computeVersionDistances(handle, cache);
+}
+/**
+ * Find the version most similar to a query.
+ *
+ * @param handle Handle name
+ * @param query Search query text
+ * @param store Optional custom HandleVectorStore instance
+ * @returns Most similar version, or undefined if no versions exist
+ */
+export async function findMostSimilarVersion(handle, query, store) {
+    const results = await searchWithinHandle(handle, query, 1, store);
+    return results.length > 0 ? results[0] : undefined;
+}
+/**
+ * Get the semantic evolution of a handle's versions.
+ *
+ * Returns version history annotated with semantic deltas,
+ * showing how content has evolved over time.
+ *
+ * @param handle Handle name
+ * @param store Optional custom HandleVectorStore instance
+ * @returns List of version objects with evolution info
+ */
+export function getSemanticEvolution(handle, store) {
+    const s = store ?? getStore();
+    const versions = s.getHandleVersions(handle);
+    return versions.map(v => {
+        let interpretation;
+        if (v.parentHash && v.semanticDelta !== undefined) {
+            if (v.semanticDelta >= 0.95) {
+                interpretation = 'Nearly identical to parent';
+            }
+            else if (v.semanticDelta >= 0.85) {
+                interpretation = 'Minor changes from parent';
+            }
+            else if (v.semanticDelta >= 0.70) {
+                interpretation = 'Significant changes from parent';
+            }
+            else {
+                interpretation = 'Major semantic shift from parent';
+            }
+        }
+        else {
+            interpretation = 'Initial version (no parent)';
+        }
+        return {
+            hash: v.hash,
+            version: v.versionOrder,
+            isCurrent: v.isCurrent,
+            createdAt: v.createdAt,
+            parentHash: v.parentHash,
+            semanticDelta: v.semanticDelta,
+            upgradeType: v.upgradeType,
+            interpretation,
+        };
+    });
+}
+// ─────────────────────────────────────────────────────────────────────────────
+// Utility Functions
+// ─────────────────────────────────────────────────────────────────────────────
+/**
+ * List all handles with indexed versions.
+ *
+ * @param store Optional custom HandleVectorStore instance
+ * @returns List of handle names
+ */
+export function listHandles(store) {
+    const s = store ?? getStore();
+    return s.listHandles();
+}
+/**
+ * Get information about the vector store.
+ *
+ * @param store Optional custom HandleVectorStore instance
+ * @returns Object with store statistics
+ */
+export function getStoreInfo(store) {
+    const s = store ?? getStore();
+    return s.getInfo();
+}
+//# sourceMappingURL=semanticVersioning.js.map

package/dist/rag/semanticVersioning.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"semanticVersioning.js","sourceRoot":"","sources":["../../src/rag/semanticVersioning.ts"],"names":[],"mappings":"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"}

package/dist/storage/IndexedDBEngine.d.ts

@@ -0,0 +1,33 @@
+import { MCard } from '../model/MCard';
+import { StorageEngine, Page } from './StorageAdapter';
+/**
+ * IndexedDBEngine - Browser storage using IndexedDB
+ */
+export declare class IndexedDBEngine implements StorageEngine {
+    private db;
+    private dbName;
+    constructor(dbName?: string);
+    /**
+     * Initialize the database connection
+     */
+    init(): Promise<void>;
+    private ensureDb;
+    add(card: MCard): Promise<string>;
+    get(hash: string): Promise<MCard | null>;
+    delete(hash: string): Promise<void>;
+    getPage(pageNumber: number, pageSize: number): Promise<Page<MCard>>;
+    count(): Promise<number>;
+    searchByHash(hashPrefix: string): Promise<MCard[]>;
+    search(query: string, pageNumber: number, pageSize: number): Promise<Page<MCard>>;
+    getAll(): Promise<MCard[]>;
+    clear(): Promise<void>;
+    registerHandle(handle: string, hash: string): Promise<void>;
+    resolveHandle(handle: string): Promise<string | null>;
+    getByHandle(handle: string): Promise<MCard | null>;
+    updateHandle(handle: string, newHash: string): Promise<string>;
+    getHandleHistory(handle: string): Promise<{
+        previousHash: string;
+        changedAt: string;
+    }[]>;
+}
+//# sourceMappingURL=IndexedDBEngine.d.ts.map

package/dist/storage/IndexedDBEngine.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"IndexedDBEngine.d.ts","sourceRoot":"","sources":["../../src/storage/IndexedDBEngine.ts"],"names":[],"mappings":"AACA,OAAO,EAAE,KAAK,EAAE,MAAM,gBAAgB,CAAC;AAEvC,OAAO,EAAE,aAAa,EAAE,IAAI,EAAE,MAAM,kBAAkB,CAAC;AAgCvD;;GAEG;AACH,qBAAa,eAAgB,YAAW,aAAa;IACjD,OAAO,CAAC,EAAE,CAA4C;IACtD,OAAO,CAAC,MAAM,CAAS;gBAEX,MAAM,GAAE,MAAmB;IAIvC;;OAEG;IACG,IAAI,IAAI,OAAO,CAAC,IAAI,CAAC;IA0B3B,OAAO,CAAC,QAAQ;IASV,GAAG,CAAC,IAAI,EAAE,KAAK,GAAG,OAAO,CAAC,MAAM,CAAC;IAUjC,GAAG,CAAC,IAAI,EAAE,MAAM,GAAG,OAAO,CAAC,KAAK,GAAG,IAAI,CAAC;IAOxC,MAAM,CAAC,IAAI,EAAE,MAAM,GAAG,OAAO,CAAC,IAAI,CAAC;IAKnC,OAAO,CAAC,UAAU,EAAE,MAAM,EAAE,QAAQ,EAAE,MAAM,GAAG,OAAO,CAAC,IAAI,CAAC,KAAK,CAAC,CAAC;IAsBnE,KAAK,IAAI,OAAO,CAAC,MAAM,CAAC;IAKxB,YAAY,CAAC,UAAU,EAAE,MAAM,GAAG,OAAO,CAAC,KAAK,EAAE,CAAC;IASlD,MAAM,CAAC,KAAK,EAAE,MAAM,EAAE,UAAU,EAAE,MAAM,EAAE,QAAQ,EAAE,MAAM,GAAG,OAAO,CAAC,IAAI,CAAC,KAAK,CAAC,CAAC;IAkCjF,MAAM,IAAI,OAAO,CAAC,KAAK,EAAE,CAAC;IAM1B,KAAK,IAAI,OAAO,CAAC,IAAI,CAAC;IAStB,cAAc,CAAC,MAAM,EAAE,MAAM,EAAE,IAAI,EAAE,MAAM,GAAG,OAAO,CAAC,IAAI,CAAC;IAkB3D,aAAa,CAAC,MAAM,EAAE,MAAM,GAAG,OAAO,CAAC,MAAM,GAAG,IAAI,CAAC;IAOrD,WAAW,CAAC,MAAM,EAAE,MAAM,GAAG,OAAO,CAAC,KAAK,GAAG,IAAI,CAAC;IAMlD,YAAY,CAAC,MAAM,EAAE,MAAM,EAAE,OAAO,EAAE,MAAM,GAAG,OAAO,CAAC,MAAM,CAAC;IA6B9D,gBAAgB,CAAC,MAAM,EAAE,MAAM,GAAG,OAAO,CAAC;QAAE,YAAY,EAAE,MAAM,CAAC;QAAC,SAAS,EAAE,MAAM,CAAA;KAAE,EAAE,CAAC;CAQjG"}

package/dist/storage/IndexedDBEngine.js

@@ -0,0 +1,198 @@
+import { openDB } from 'idb';
+import { MCard } from '../model/MCard';
+import { validateHandle } from '../model/Handle';
+/**
+ * IndexedDBEngine - Browser storage using IndexedDB
+ */
+export class IndexedDBEngine {
+    db = null;
+    dbName;
+    constructor(dbName = 'mcard-db') {
+        this.dbName = dbName;
+    }
+    /**
+     * Initialize the database connection
+     */
+    async init() {
+        this.db = await openDB(this.dbName, 1, {
+            upgrade(db) {
+                // Cards store
+                if (!db.objectStoreNames.contains('cards')) {
+                    db.createObjectStore('cards', { keyPath: 'hash' });
+                }
+                // Handles store
+                if (!db.objectStoreNames.contains('handles')) {
+                    const handleStore = db.createObjectStore('handles', { keyPath: 'handle' });
+                    handleStore.createIndex('by-hash', 'currentHash');
+                }
+                // Handle history store
+                if (!db.objectStoreNames.contains('handleHistory')) {
+                    const historyStore = db.createObjectStore('handleHistory', {
+                        keyPath: 'id',
+                        autoIncrement: true
+                    });
+                    historyStore.createIndex('by-handle', 'handle');
+                }
+            }
+        });
+    }
+    ensureDb() {
+        if (!this.db) {
+            throw new Error('Database not initialized. Call init() first.');
+        }
+        return this.db;
+    }
+    // =========== Card Operations ===========
+    async add(card) {
+        const db = this.ensureDb();
+        await db.put('cards', {
+            hash: card.hash,
+            content: card.content,
+            g_time: card.g_time
+        });
+        return card.hash;
+    }
+    async get(hash) {
+        const db = this.ensureDb();
+        const record = await db.get('cards', hash);
+        if (!record)
+            return null;
+        return MCard.fromData(record.content, record.hash, record.g_time);
+    }
+    async delete(hash) {
+        const db = this.ensureDb();
+        await db.delete('cards', hash);
+    }
+    async getPage(pageNumber, pageSize) {
+        const db = this.ensureDb();
+        const totalItems = await db.count('cards');
+        const totalPages = Math.ceil(totalItems / pageSize);
+        const allCards = await db.getAll('cards');
+        const start = (pageNumber - 1) * pageSize;
+        const pageRecords = allCards.slice(start, start + pageSize);
+        const items = pageRecords.map(r => MCard.fromData(r.content, r.hash, r.g_time));
+        return {
+            items,
+            totalItems,
+            pageNumber,
+            pageSize,
+            totalPages,
+            hasNext: pageNumber < totalPages,
+            hasPrevious: pageNumber > 1
+        };
+    }
+    async count() {
+        const db = this.ensureDb();
+        return db.count('cards');
+    }
+    async searchByHash(hashPrefix) {
+        const db = this.ensureDb();
+        const start = hashPrefix;
+        const end = hashPrefix + '\uffff';
+        const range = IDBKeyRange.bound(start, end);
+        const records = await db.getAll('cards', range);
+        return records.map(r => MCard.fromData(r.content, r.hash, r.g_time));
+    }
+    async search(query, pageNumber, pageSize) {
+        const db = this.ensureDb();
+        // Naive implementation: load all and filter
+        // Optimized implementation would use a full-text index if available
+        const records = await db.getAll('cards');
+        const decoder = new TextDecoder();
+        const filtered = records.filter(r => {
+            // Try to match query in content if it looks like text
+            try {
+                const text = decoder.decode(r.content);
+                return text.includes(query);
+            }
+            catch {
+                return false;
+            }
+        });
+        const totalItems = filtered.length;
+        const totalPages = Math.ceil(totalItems / pageSize);
+        const start = (pageNumber - 1) * pageSize;
+        const pageItems = filtered.slice(start, start + pageSize)
+            .map(r => MCard.fromData(r.content, r.hash, r.g_time));
+        return {
+            items: pageItems,
+            totalItems,
+            pageNumber,
+            pageSize,
+            totalPages,
+            hasNext: pageNumber < totalPages,
+            hasPrevious: pageNumber > 1
+        };
+    }
+    async getAll() {
+        const db = this.ensureDb();
+        const records = await db.getAll('cards');
+        return records.map(r => MCard.fromData(r.content, r.hash, r.g_time));
+    }
+    async clear() {
+        const db = this.ensureDb();
+        await db.clear('cards');
+        await db.clear('handles');
+        await db.clear('handleHistory');
+    }
+    // =========== Handle Operations ===========
+    async registerHandle(handle, hash) {
+        const db = this.ensureDb();
+        const normalized = validateHandle(handle);
+        const existing = await db.get('handles', normalized);
+        if (existing) {
+            throw new Error(`Handle '${handle}' already exists.`);
+        }
+        const now = new Date().toISOString();
+        await db.put('handles', {
+            handle: normalized,
+            currentHash: hash,
+            createdAt: now,
+            updatedAt: now
+        });
+    }
+    async resolveHandle(handle) {
+        const db = this.ensureDb();
+        const normalized = validateHandle(handle);
+        const record = await db.get('handles', normalized);
+        return record?.currentHash ?? null;
+    }
+    async getByHandle(handle) {
+        const hash = await this.resolveHandle(handle);
+        if (!hash)
+            return null;
+        return this.get(hash);
+    }
+    async updateHandle(handle, newHash) {
+        const db = this.ensureDb();
+        const normalized = validateHandle(handle);
+        const existing = await db.get('handles', normalized);
+        if (!existing) {
+            throw new Error(`Handle '${handle}' not found.`);
+        }
+        const previousHash = existing.currentHash;
+        const now = new Date().toISOString();
+        // Record history
+        await db.add('handleHistory', {
+            handle: normalized,
+            previousHash,
+            changedAt: now
+        });
+        // Update handle
+        await db.put('handles', {
+            ...existing,
+            currentHash: newHash,
+            updatedAt: now
+        });
+        return previousHash;
+    }
+    async getHandleHistory(handle) {
+        const db = this.ensureDb();
+        const normalized = validateHandle(handle);
+        const records = await db.getAllFromIndex('handleHistory', 'by-handle', normalized);
+        return records
+            .map(r => ({ previousHash: r.previousHash, changedAt: r.changedAt }))
+            .reverse(); // Newest first
+    }
+}
+//# sourceMappingURL=IndexedDBEngine.js.map