mcard-js 2.1.49 → 2.1.51

package/dist/chunk-4DFTWDRB.js

@@ -0,0 +1,497 @@
+import {
+  createPage
+} from "./chunk-3EIBJPNF.js";
+import {
+  init_Handle,
+  validateHandle
+} from "./chunk-ADV52544.js";
+import {
+  DEFAULT_PAGE_SIZE
+} from "./chunk-PKLONZCF.js";
+
+// src/storage/schema.ts
+import { get_core_schema, get_vector_schema } from "mcard-wasm";
+var TABLE_LAYERS = {
+  // Layer 1: Core
+  "card": "core",
+  // Layer 2: Handle System
+  "handle_registry": "handle",
+  "handle_history": "handle",
+  // Layer 3: Vector Storage
+  "mcard_vector_metadata": "vector",
+  "mcard_embeddings": "vector",
+  "mcard_fts": "vector",
+  // Layer 4: Semantic Versioning
+  "handle_version_vectors": "semantic",
+  "version_similarity_cache": "semantic",
+  // Layer 5: Knowledge Graph
+  "graph_entities": "graph",
+  "graph_relationships": "graph",
+  "graph_communities": "graph",
+  "graph_extractions": "graph",
+  // Metadata
+  "schema_version": "metadata"
+};
+var MCardSchema = class _MCardSchema {
+  static instance = null;
+  schemaPath = "";
+  rawSql = "";
+  statements = [];
+  tables = /* @__PURE__ */ new Map();
+  indexes = /* @__PURE__ */ new Map();
+  loaded = false;
+  constructor() {
+  }
+  /**
+   * Get the singleton instance.
+   */
+  static getInstance() {
+    if (!_MCardSchema.instance) {
+      _MCardSchema.instance = new _MCardSchema();
+      _MCardSchema.instance.load();
+    }
+    return _MCardSchema.instance;
+  }
+  /**
+   * Reset the singleton (for testing).
+   */
+  static resetInstance() {
+    _MCardSchema.instance = null;
+  }
+  load() {
+    if (this.loaded) return;
+    this.schemaPath = "WASM_MEMORY_SPACE";
+    this.rawSql = get_core_schema();
+    const vectorSql = get_vector_schema();
+    if (vectorSql) {
+      this.rawSql += "\n\n" + vectorSql;
+    }
+    this.statements = this.parseStatements(this.rawSql);
+    for (const stmt of this.statements) {
+      const name = this.extractName(stmt);
+      if (name) {
+        const upper = stmt.toUpperCase();
+        if (upper.includes("CREATE TABLE") || upper.includes("CREATE VIRTUAL TABLE")) {
+          this.tables.set(name.toLowerCase(), stmt);
+        } else if (upper.includes("CREATE INDEX")) {
+          this.indexes.set(name.toLowerCase(), stmt);
+        }
+      }
+    }
+    this.loaded = true;
+  }
+  parseStatements(sql) {
+    sql = sql.replace(/\/\*[\s\S]*?\*\//g, "");
+    const statements = [];
+    let current = [];
+    for (const line of sql.split("\n")) {
+      const stripped = line.split("--")[0].trim();
+      if (!stripped) continue;
+      current.push(stripped);
+      if (stripped.endsWith(";")) {
+        const statement = current.join(" ");
+        if (!statement.trim().toUpperCase().startsWith("INSERT")) {
+          statements.push(statement);
+        }
+        current = [];
+      }
+    }
+    return statements.filter((s) => s.trim());
+  }
+  extractName(statement) {
+    let match = statement.match(/CREATE\s+(?:VIRTUAL\s+)?TABLE\s+(?:IF\s+NOT\s+EXISTS\s+)?(\w+)/i);
+    if (match) return match[1];
+    match = statement.match(/CREATE\s+INDEX\s+(?:IF\s+NOT\s+EXISTS\s+)?(\w+)/i);
+    if (match) return match[1];
+    return null;
+  }
+  // ─────────────────────────────────────────────────────────────────────────
+  // Schema Access
+  // ─────────────────────────────────────────────────────────────────────────
+  getSchemaPath() {
+    return this.schemaPath;
+  }
+  getTable(tableName) {
+    return this.tables.get(tableName.toLowerCase());
+  }
+  getIndex(indexName) {
+    return this.indexes.get(indexName.toLowerCase());
+  }
+  getAllTables() {
+    return new Map(this.tables);
+  }
+  getAllIndexes() {
+    return new Map(this.indexes);
+  }
+  getAllStatements() {
+    return [...this.statements];
+  }
+  getTablesByLayer(layer) {
+    return Object.entries(TABLE_LAYERS).filter(([_, l]) => l === layer).map(([name, _]) => name);
+  }
+  getLayerStatements(layer) {
+    const statements = [];
+    const tables = this.getTablesByLayer(layer);
+    for (const table of tables) {
+      const stmt = this.getTable(table);
+      if (stmt) statements.push(stmt);
+    }
+    for (const [_, stmt] of this.indexes) {
+      const match = stmt.match(/ON\s+(\w+)/i);
+      if (match && tables.includes(match[1].toLowerCase())) {
+        statements.push(stmt);
+      }
+    }
+    return statements;
+  }
+  // ─────────────────────────────────────────────────────────────────────────
+  // Database Initialization
+  // ─────────────────────────────────────────────────────────────────────────
+  execStatements(db, statements) {
+    for (const stmt of statements) {
+      db.exec(stmt);
+    }
+    return statements.length;
+  }
+  initLayer(db, layer) {
+    return this.execStatements(db, this.getLayerStatements(layer));
+  }
+  initCoreTables(db) {
+    return this.initLayer(db, "core");
+  }
+  initHandleTables(db) {
+    return this.initLayer(db, "handle");
+  }
+  initVectorTables(db, enableFts = true) {
+    const statements = this.getLayerStatements("vector").filter((s) => enableFts || !s.toLowerCase().includes("fts"));
+    return this.execStatements(db, statements);
+  }
+  initSemanticTables(db) {
+    return this.initLayer(db, "semantic");
+  }
+  initGraphTables(db) {
+    return this.initLayer(db, "graph");
+  }
+  initAllTables(db, options = {}) {
+    const { enableFts = true, enableGraph = true, enableSemantic = true } = options;
+    let count = 0;
+    count += this.initCoreTables(db);
+    count += this.initHandleTables(db);
+    count += this.initVectorTables(db, enableFts);
+    if (enableSemantic) {
+      count += this.initSemanticTables(db);
+    }
+    if (enableGraph) {
+      count += this.initGraphTables(db);
+    }
+    return count;
+  }
+  initVec0Table(db, dimensions) {
+    db.exec(`
+            CREATE VIRTUAL TABLE IF NOT EXISTS mcard_vec USING vec0(
+                metadata_id INTEGER PRIMARY KEY,
+                embedding float[${dimensions}]
+            )
+        `);
+  }
+};
+function getSchemaInstance() {
+  return MCardSchema.getInstance();
+}
+var CARD_TABLE_SCHEMA = getSchemaInstance().getTable("card") || "";
+var HANDLE_REGISTRY_SCHEMA = getSchemaInstance().getTable("handle_registry") || "";
+var HANDLE_HISTORY_SCHEMA = getSchemaInstance().getTable("handle_history") || "";
+var HANDLE_INDEX_SCHEMA = getSchemaInstance().getIndex("idx_handle_current_hash") || "";
+var VECTOR_METADATA_SCHEMA = getSchemaInstance().getTable("mcard_vector_metadata") || "";
+var VECTOR_METADATA_INDEX = getSchemaInstance().getIndex("idx_vector_metadata_hash") || "";
+var VECTOR_EMBEDDINGS_SCHEMA = getSchemaInstance().getTable("mcard_embeddings") || "";
+var VECTOR_FTS_SCHEMA = getSchemaInstance().getTable("mcard_fts") || "";
+var HANDLE_VERSION_VECTORS_SCHEMA = getSchemaInstance().getTable("handle_version_vectors") || "";
+var HANDLE_VERSION_VECTORS_INDEXES = [
+  getSchemaInstance().getIndex("idx_hvv_handle"),
+  getSchemaInstance().getIndex("idx_hvv_hash"),
+  getSchemaInstance().getIndex("idx_hvv_current"),
+  getSchemaInstance().getIndex("idx_hvv_parent")
+].filter(Boolean).join("; ");
+var VERSION_SIMILARITY_CACHE_SCHEMA = getSchemaInstance().getTable("version_similarity_cache") || "";
+var VERSION_SIMILARITY_CACHE_INDEX = getSchemaInstance().getIndex("idx_vsc_handle") || "";
+var GRAPH_ENTITY_SCHEMA = getSchemaInstance().getTable("graph_entities") || "";
+var GRAPH_ENTITY_INDEX_NAME = getSchemaInstance().getIndex("idx_entity_name") || "";
+var GRAPH_ENTITY_INDEX_TYPE = getSchemaInstance().getIndex("idx_entity_type") || "";
+var GRAPH_ENTITY_INDEX_SOURCE = getSchemaInstance().getIndex("idx_entity_source") || "";
+var GRAPH_RELATIONSHIP_SCHEMA = getSchemaInstance().getTable("graph_relationships") || "";
+var GRAPH_RELATIONSHIP_INDEX_SOURCE = getSchemaInstance().getIndex("idx_rel_source") || "";
+var GRAPH_RELATIONSHIP_INDEX_TARGET = getSchemaInstance().getIndex("idx_rel_target") || "";
+var GRAPH_COMMUNITY_SCHEMA = getSchemaInstance().getTable("graph_communities") || "";
+var GRAPH_COMMUNITY_INDEX_LEVEL = getSchemaInstance().getIndex("idx_community_level") || "";
+var GRAPH_EXTRACTION_SCHEMA = getSchemaInstance().getTable("graph_extractions") || "";
+var CORE_SCHEMAS = {
+  card: CARD_TABLE_SCHEMA,
+  handleRegistry: HANDLE_REGISTRY_SCHEMA,
+  handleHistory: HANDLE_HISTORY_SCHEMA,
+  handleIndex: HANDLE_INDEX_SCHEMA
+};
+function initCoreSchemas(db) {
+  const schema = MCardSchema.getInstance();
+  schema.initCoreTables(db);
+  schema.initHandleTables(db);
+}
+
+// src/storage/engines/AbstractSqlEngine.ts
+init_Handle();
+var AbstractSqlEngine = class {
+  /**
+   * SQL expression for casting content to text in search queries.
+   * Override in subclasses: SQLite uses 'TEXT', DuckDB uses 'VARCHAR'.
+   */
+  get castContentAs() {
+    return "TEXT";
+  }
+  // ======================================================================
+  // Concrete: Card Operations (shared across all SQL engines)
+  // ======================================================================
+  /**
+   * Add a card. Default uses INSERT OR REPLACE (SQLite).
+   * DuckDB overrides with DELETE + INSERT.
+   */
+  async add(card) {
+    const contentBytes = card.content instanceof Uint8Array ? card.content : new TextEncoder().encode(String(card.content));
+    await this.execSql(
+      "INSERT OR REPLACE INTO card (hash, content, g_time) VALUES (?, ?, ?)",
+      card.hash,
+      contentBytes,
+      card.g_time
+    );
+    return card.hash;
+  }
+  async get(hash) {
+    const rows = await this.queryRows(
+      "SELECT hash, content, g_time FROM card WHERE hash = ?",
+      hash
+    );
+    if (rows.length === 0) return null;
+    return this.rowToCard(rows[0]);
+  }
+  async delete(hash) {
+    await this.execSql("DELETE FROM card WHERE hash = ?", hash);
+  }
+  async getPage(pageNumber = 1, pageSize = DEFAULT_PAGE_SIZE) {
+    if (pageNumber < 1) throw new Error("Page number must be >= 1");
+    if (pageSize < 1) throw new Error("Page size must be >= 1");
+    const totalItems = await this.count();
+    const offset = (pageNumber - 1) * pageSize;
+    const rows = await this.queryRows(
+      "SELECT hash, content, g_time FROM card ORDER BY g_time DESC LIMIT ? OFFSET ?",
+      pageSize,
+      offset
+    );
+    const items = rows.map((r) => this.rowToCard(r));
+    return createPage(items, totalItems, pageNumber, pageSize);
+  }
+  async count() {
+    const rows = await this.queryRows("SELECT COUNT(*) as cnt FROM card");
+    return Number(rows[0]?.cnt ?? 0);
+  }
+  async searchByHash(hashPrefix) {
+    const rows = await this.queryRows(
+      "SELECT hash, content, g_time FROM card WHERE hash LIKE ?",
+      `${hashPrefix}%`
+    );
+    return rows.map((r) => this.rowToCard(r));
+  }
+  async search(queryStr, pageNumber = 1, pageSize = DEFAULT_PAGE_SIZE) {
+    if (pageNumber < 1) throw new Error("Page number must be >= 1");
+    if (pageSize < 1) throw new Error("Page size must be >= 1");
+    const offset = (pageNumber - 1) * pageSize;
+    const pattern = `%${queryStr}%`;
+    const cast = this.castContentAs;
+    const countRows = await this.queryRows(
+      `SELECT COUNT(*) as cnt FROM card WHERE CAST(content AS ${cast}) LIKE ?`,
+      pattern
+    );
+    const totalItems = Number(countRows[0]?.cnt ?? 0);
+    const rows = await this.queryRows(
+      `SELECT hash, content, g_time FROM card WHERE CAST(content AS ${cast}) LIKE ? ORDER BY g_time DESC LIMIT ? OFFSET ?`,
+      pattern,
+      pageSize,
+      offset
+    );
+    const items = rows.map((r) => this.rowToCard(r));
+    return createPage(items, totalItems, pageNumber, pageSize);
+  }
+  async getAll() {
+    const rows = await this.queryRows("SELECT hash, content, g_time FROM card ORDER BY g_time DESC");
+    return rows.map((r) => this.rowToCard(r));
+  }
+  // ======================================================================
+  // Concrete: clear (FK-safe delete order)
+  // ======================================================================
+  async clear() {
+    await this.execSql("DELETE FROM handle_history");
+    await this.execSql("DELETE FROM handle_registry");
+    await this.execSql("DELETE FROM card");
+  }
+  // ======================================================================
+  // Concrete: Handle Operations
+  // ======================================================================
+  async registerHandle(handle, hash) {
+    const normalized = validateHandle(handle);
+    const now = (/* @__PURE__ */ new Date()).toISOString();
+    const existing = await this.queryRows(
+      "SELECT handle FROM handle_registry WHERE handle = ?",
+      normalized
+    );
+    if (existing.length > 0) {
+      throw new Error(`Handle '${handle}' already exists.`);
+    }
+    await this.execSql(
+      "INSERT INTO handle_registry (handle, current_hash, created_at, updated_at) VALUES (?, ?, ?, ?)",
+      normalized,
+      hash,
+      now,
+      now
+    );
+  }
+  async resolveHandle(handle) {
+    const normalized = validateHandle(handle);
+    const rows = await this.queryRows(
+      "SELECT current_hash FROM handle_registry WHERE handle = ?",
+      normalized
+    );
+    if (rows.length === 0) return null;
+    return String(rows[0].current_hash);
+  }
+  async getByHandle(handle) {
+    const hash = await this.resolveHandle(handle);
+    if (!hash) return null;
+    return this.get(hash);
+  }
+  async updateHandle(handle, newHash) {
+    const normalized = validateHandle(handle);
+    const now = (/* @__PURE__ */ new Date()).toISOString();
+    const rows = await this.queryRows(
+      "SELECT current_hash FROM handle_registry WHERE handle = ?",
+      normalized
+    );
+    if (rows.length === 0) {
+      throw new Error(`Handle '${handle}' not found.`);
+    }
+    const previousHash = String(rows[0].current_hash);
+    await this.execSql(
+      "INSERT INTO handle_history (handle, previous_hash, changed_at) VALUES (?, ?, ?)",
+      normalized,
+      previousHash,
+      now
+    );
+    await this.execSql(
+      "UPDATE handle_registry SET current_hash = ?, updated_at = ? WHERE handle = ?",
+      newHash,
+      now,
+      normalized
+    );
+    return previousHash;
+  }
+  async getHandleHistory(handle) {
+    const normalized = validateHandle(handle);
+    const rows = await this.queryRows(
+      "SELECT previous_hash, changed_at FROM handle_history WHERE handle = ? ORDER BY id DESC",
+      normalized
+    );
+    return rows.map((r) => ({
+      previousHash: String(r.previous_hash),
+      changedAt: String(r.changed_at)
+    }));
+  }
+  async pruneHandleHistory(handle, options = {}) {
+    const normalized = validateHandle(handle);
+    if (options.deleteAll) {
+      return this.execSql("DELETE FROM handle_history WHERE handle = ?", normalized);
+    } else if (options.olderThan) {
+      return this.execSql(
+        "DELETE FROM handle_history WHERE handle = ? AND changed_at < ?",
+        normalized,
+        options.olderThan
+      );
+    }
+    return 0;
+  }
+  // ======================================================================
+  // Concrete: Handle Management Operations
+  // ======================================================================
+  async getAllHandles() {
+    const rows = await this.queryRows("SELECT handle, current_hash FROM handle_registry");
+    return rows.map((r) => ({
+      handle: String(r.handle),
+      hash: String(r.current_hash)
+    }));
+  }
+  async removeHandle(handle) {
+    const normalized = validateHandle(handle);
+    await this.execSql("DELETE FROM handle_history WHERE handle = ?", normalized);
+    await this.execSql("DELETE FROM handle_registry WHERE handle = ?", normalized);
+  }
+  async renameHandle(oldHandle, newHandle) {
+    const normalizedOld = validateHandle(oldHandle);
+    const normalizedNew = validateHandle(newHandle);
+    if (normalizedOld === normalizedNew) return;
+    const existsOld = await this.queryRows(
+      "SELECT handle FROM handle_registry WHERE handle = ?",
+      normalizedOld
+    );
+    if (existsOld.length === 0) throw new Error(`Handle '${oldHandle}' not found.`);
+    const existsNew = await this.queryRows(
+      "SELECT handle FROM handle_registry WHERE handle = ?",
+      normalizedNew
+    );
+    if (existsNew.length > 0) throw new Error(`Handle '${newHandle}' already exists.`);
+    const oldRow = await this.queryRows(
+      "SELECT current_hash, created_at, updated_at FROM handle_registry WHERE handle = ?",
+      normalizedOld
+    );
+    await this.execSql(
+      "INSERT INTO handle_registry (handle, current_hash, created_at, updated_at) VALUES (?, ?, ?, ?)",
+      normalizedNew,
+      String(oldRow[0].current_hash),
+      String(oldRow[0].created_at),
+      String(oldRow[0].updated_at)
+    );
+    await this.execSql(
+      "UPDATE handle_history SET handle = ? WHERE handle = ?",
+      normalizedNew,
+      normalizedOld
+    );
+    await this.execSql(
+      "DELETE FROM handle_registry WHERE handle = ?",
+      normalizedOld
+    );
+  }
+  async deleteHistoryEntry(handle, previousHash) {
+    const normalized = validateHandle(handle);
+    const rOutRows = await this.queryRows(
+      "SELECT id, previous_hash FROM handle_history WHERE handle = ? AND previous_hash = ? ORDER BY id DESC LIMIT 1",
+      normalized,
+      previousHash
+    );
+    if (rOutRows.length === 0) return;
+    const rOutId = Number(rOutRows[0].id);
+    const rInRows = await this.queryRows(
+      "SELECT id, previous_hash FROM handle_history WHERE handle = ? AND id < ? ORDER BY id DESC LIMIT 1",
+      normalized,
+      rOutId
+    );
+    if (rInRows.length > 0) {
+      const rInId = Number(rInRows[0].id);
+      const rInPrevHash = String(rInRows[0].previous_hash);
+      await this.execSql("UPDATE handle_history SET previous_hash = ? WHERE id = ?", rInPrevHash, rOutId);
+      await this.execSql("DELETE FROM handle_history WHERE id = ?", rInId);
+    } else {
+      await this.execSql("DELETE FROM handle_history WHERE id = ?", rOutId);
+    }
+  }
+};
+
+export {
+  CORE_SCHEMAS,
+  initCoreSchemas,
+  AbstractSqlEngine
+};

package/dist/chunk-4PBRTFSY.js

@@ -0,0 +1,112 @@
+import {
+  AbstractSqlEngine,
+  CORE_SCHEMAS
+} from "./chunk-DM2ABCA4.js";
+import {
+  MCard
+} from "./chunk-GGQCF7ZK.js";
+import {
+  DEFAULT_SQLJS_WASM_URL
+} from "./chunk-R3XRBAM7.js";
+
+// src/storage/engines/SqliteWasmEngine.ts
+var SqliteWasmEngine = class extends AbstractSqlEngine {
+  db = null;
+  SQL = null;
+  /**
+   * Initialize the database
+   * @param wasmUrl URL to sql-wasm.wasm file (optional, defaults to CDN)
+   * @param existingData Optional existing database as Uint8Array
+   */
+  async init(wasmUrl, existingData) {
+    const initSqlJs = (await import("sql.js")).default;
+    const SQL = await initSqlJs({
+      locateFile: (file) => wasmUrl || `${DEFAULT_SQLJS_WASM_URL}${file}`
+    });
+    this.SQL = SQL;
+    this.db = existingData ? new SQL.Database(existingData) : new SQL.Database();
+    this.db.run(CORE_SCHEMAS.card);
+    this.db.run(CORE_SCHEMAS.handleRegistry);
+    this.db.run(CORE_SCHEMAS.handleHistory);
+    this.db.run(CORE_SCHEMAS.handleIndex);
+  }
+  ensureDb() {
+    if (!this.db) throw new Error("Database not initialized. Call init() first.");
+    return this.db;
+  }
+  // ======================================================================
+  // AbstractSqlEngine primitives
+  // ======================================================================
+  async queryRows(sql, ...params) {
+    const db = this.ensureDb();
+    const stmt = db.prepare(sql);
+    if (params.length > 0) stmt.bind(params);
+    const results = [];
+    while (stmt.step()) {
+      const row = stmt.getAsObject();
+      results.push(row);
+    }
+    stmt.free();
+    return results;
+  }
+  async execSql(sql, ...params) {
+    const db = this.ensureDb();
+    if (params.length === 0) {
+      db.run(sql);
+    } else {
+      db.run(sql, params);
+    }
+    return 0;
+  }
+  // ======================================================================
+  // Row → MCard conversion (sql.js returns Uint8Array for BLOBs)
+  // ======================================================================
+  rowToCard(row) {
+    const rawContent = row.content;
+    const content = rawContent instanceof Uint8Array ? rawContent : typeof rawContent === "string" ? new TextEncoder().encode(rawContent) : new Uint8Array(0);
+    return MCard.fromData(content, String(row.hash), String(row.g_time));
+  }
+  // ======================================================================
+  // sql.js-specific helpers
+  // ======================================================================
+  /**
+   * Export database as Uint8Array (for persistence)
+   */
+  export() {
+    return this.ensureDb().export();
+  }
+  /**
+   * Get raw sql.js Database for use with VectorStore adapter.
+   */
+  getRawDb() {
+    return this.ensureDb();
+  }
+  // =========== pruneHandleHistory override (needs count before delete) ===========
+  async pruneHandleHistory(handle, options = {}) {
+    const { validateHandle } = await import("./Handle-3N4QOA3U.js");
+    const db = this.ensureDb();
+    const normalized = validateHandle(handle);
+    if (options.deleteAll) {
+      const stmt = db.prepare("SELECT COUNT(*) FROM handle_history WHERE handle = ?");
+      stmt.bind([normalized]);
+      stmt.step();
+      const count = stmt.get()[0];
+      stmt.free();
+      db.run("DELETE FROM handle_history WHERE handle = ?", [normalized]);
+      return count;
+    } else if (options.olderThan) {
+      const stmt = db.prepare("SELECT COUNT(*) FROM handle_history WHERE handle = ? AND changed_at < ?");
+      stmt.bind([normalized, options.olderThan]);
+      stmt.step();
+      const count = stmt.get()[0];
+      stmt.free();
+      db.run("DELETE FROM handle_history WHERE handle = ? AND changed_at < ?", [normalized, options.olderThan]);
+      return count;
+    }
+    return 0;
+  }
+};
+
+export {
+  SqliteWasmEngine
+};