mcard-js/dist/storage/schema_constants.js

MCard - Content-addressable storage with cryptographic hashing, handle resolution, and vector search for Node.js and browsers

/**
 * AUTO-GENERATED FILE - DO NOT EDIT
 * Generated by scripts/sync-schemas.js
 */
export const MCARD_SCHEMA_SQL = `-- ═══════════════════════════════════════════════════════════════════════════════
-- MCard Unified Database Schema (Monadic Core)
-- ═══════════════════════════════════════════════════════════════════════════════
-- 
-- STABILITY WARNING: This schema is the invariant "seeding meta-language" for all
-- Domain Specific Languages (DSLs). It must remain as stable as possible.
--
-- THE UNIFICATION THESIS:
-- This design unites three distinct namespaces into a single relational network
-- by leveraging the power of cryptographic hash functions:
-- 1. CONTENT SPACE (Intrinsic Identity): Content-Addressable Storage (CAS).
-- 2. HANDLE SPACE (Reserved Words): Mapping human logic to content hashes.
-- 3. VERSION SPACE (Temporal Evolution): Tracking state transitions via hash history.
--
-- TURING MACHINE ANALOGY (The Infinitely Long Tape):
-- The \`card\` table stores content blobs with unique identities, emulating the 
-- "Infinitely Long Tape" of the Turing Machine formalism. By using relational 
-- queries, this tape can be dynamically constructed and traversed for different 
-- DSLs, providing a flexible substrate for practically all computable languages.
--
-- By using hash values as the universal primitives across content, handles, and 
-- time, we create a "Wordless Book" — a minimal substrate capable of seeding any 
-- domain-specific knowledge system without requiring schema changes.
--
-- Monadic Mapping (See: Monadic Justification for Schema Design.md):
-- 1. Card    = Monad (Perception/State/Exponent) - Intrinsic Identity
-- 2. Handle  = Registry (Appetition/Reader/Sum) - Mutable Reference
-- 3. Version = History (Harmony/Writer/Product) - Coordinated Evolution
--
-- Version: 3.0.2 (Turing Tape Refinement)
-- Last Updated: 2025-12-20
-- ═══════════════════════════════════════════════════════════════════════════════


-- ═══════════════════════════════════════════════════════════════════════════════
-- LAYER 1: CORE CONTENT-ADDRESSABLE STORAGE (The Monad / Exponent)
-- ═══════════════════════════════════════════════════════════════════════════════
-- The fundamental MCard storage: content-addressed by cryptographic hash.
-- "Each Monad ... mirrors the universe"

-- @table card
-- @description Core content-addressable storage table (Monad/State)
-- @column hash    - SHA-256 hash of content (primary key)
-- @column content - The actual content (BLOB for binary safety)
-- @column g_time  - Generation timestamp (ISO 8601)
CREATE TABLE IF NOT EXISTS card (
    hash TEXT PRIMARY KEY,
    content BLOB NOT NULL,
    g_time TEXT NOT NULL
);


-- ═══════════════════════════════════════════════════════════════════════════════
-- LAYER 2: HANDLE SYSTEM (Appetition / Sum)
-- ═══════════════════════════════════════════════════════════════════════════════
-- The mutable pointer that "desires" to reference new content.
-- "Appetition: the tendency to move to new states"

-- @table handle_registry (Monadic Role: Handle)
-- @description Maps human-readable handles to current content hashes
-- @column handle       - UTF-8 handle name (primary key)
-- @column current_hash - FK to card.hash of current version
-- @column created_at   - When handle was first created
-- @column updated_at   - When handle was last updated
CREATE TABLE IF NOT EXISTS handle_registry (
    handle TEXT PRIMARY KEY,
    current_hash TEXT NOT NULL,
    created_at TEXT NOT NULL,
    updated_at TEXT NOT NULL,
    FOREIGN KEY (current_hash) REFERENCES card(hash)
);

-- @index idx_handle_current_hash
-- @description Efficient reverse lookup from hash to handles
CREATE INDEX IF NOT EXISTS idx_handle_current_hash 
ON handle_registry(current_hash);

-- @table handle_history (Monadic Role: Version / Product)
-- @description Audit trail for handle pointer changes (Pre-Established Harmony)
-- @column id            - Auto-increment primary key
-- @column handle        - The handle that was updated
-- @column previous_hash - Hash it pointed to before update
-- @column changed_at    - When the change occurred
CREATE TABLE IF NOT EXISTS handle_history (
    id INTEGER PRIMARY KEY AUTOINCREMENT,
    handle TEXT NOT NULL,
    previous_hash TEXT NOT NULL,
    changed_at TEXT NOT NULL,
    FOREIGN KEY (handle) REFERENCES handle_registry(handle),
    FOREIGN KEY (previous_hash) REFERENCES card(hash)
);

-- @index idx_handle_history_handle
-- @description Efficient lookup of history by handle
CREATE INDEX IF NOT EXISTS idx_handle_history_handle 
ON handle_history(handle);


-- ═══════════════════════════════════════════════════════════════════════════════
-- LEGACY SUPPORT: FTS5 Documents Table
-- ═══════════════════════════════════════════════════════════════════════════════
-- KEPT FOR BACKWARD COMPATIBILITY with existing codebase.
-- New implementations should use mcard_vector_schema.sql -> mcard_fts

-- @virtual_table documents
-- @description Legacy FTS table for backward compatibility
-- @note Synced with card table via triggers
CREATE VIRTUAL TABLE IF NOT EXISTS documents USING fts5(content);


-- ═══════════════════════════════════════════════════════════════════════════════
-- SCHEMA METADATA
-- ═══════════════════════════════════════════════════════════════════════════════

-- @table schema_version
-- @description Tracks schema version for migrations
CREATE TABLE IF NOT EXISTS schema_version (
    version TEXT PRIMARY KEY,
    applied_at TEXT NOT NULL,
    description TEXT
);

-- Insert current schema version
INSERT OR IGNORE INTO schema_version (version, applied_at, description)
VALUES ('3.0.0', datetime('now'), 'Monadic Core Schema (split vectors to mcard_vector_schema.sql)');
`;
export const MCARD_VECTOR_SCHEMA_SQL = `-- ═══════════════════════════════════════════════════════════════════════════════
-- MCard Vector Database Schema (mcard_vectors.db)
-- ═══════════════════════════════════════════════════════════════════════════════
-- 
-- This schema defines the structure for "Secondary Qualities" (Extrinsic Embeddings).
-- It is separated from the core mcard.db (Monadic Intrinsic Properties) to ensure:
-- 1. Separation of Concerns (Intrinsic vs Extrinsic)
-- 2. Linearity (Vectors are observer-dependent and large)
-- 3. Upgradability (Embedding models change frequently)
--
-- See: Monadic Justification for Schema Design.md
-- ═══════════════════════════════════════════════════════════════════════════════

-- ═══════════════════════════════════════════════════════════════════════════════
-- LAYER 3: VECTOR STORAGE (Semantic Embeddings)
-- ═══════════════════════════════════════════════════════════════════════════════
-- Storage for vector embeddings enabling semantic search.
-- Links to content via hash for content-addressing.

-- @table mcard_vector_metadata
-- @description Metadata for stored embeddings
-- @column id          - Auto-increment primary key
-- @column hash        - FK to card.hash
-- @column model_name  - Embedding model used (e.g., "nomic-embed-text")
-- @column dimensions  - Vector dimensions
-- @column chunk_index - Index for chunked documents (0 = first/whole)
-- @column chunk_total - Total chunks for this document
-- @column chunk_text  - Preview text for this chunk
-- @column created_at  - When embedding was created
CREATE TABLE IF NOT EXISTS mcard_vector_metadata (
    id INTEGER PRIMARY KEY AUTOINCREMENT,
    hash TEXT NOT NULL,
    model_name TEXT NOT NULL,
    dimensions INTEGER NOT NULL,
    chunk_index INTEGER DEFAULT 0,
    chunk_total INTEGER DEFAULT 1,
    chunk_text TEXT,
    created_at TEXT NOT NULL,
    UNIQUE(hash, chunk_index)
);

-- @index idx_vector_metadata_hash
-- @description Efficient lookup of embeddings by content hash
CREATE INDEX IF NOT EXISTS idx_vector_metadata_hash 
ON mcard_vector_metadata(hash);

-- @table mcard_embeddings
-- @description Fallback embedding storage when sqlite-vec is unavailable
-- @column id          - Auto-increment primary key
-- @column metadata_id - FK to mcard_vector_metadata.id
-- @column embedding   - Serialized float32 vector as BLOB
CREATE TABLE IF NOT EXISTS mcard_embeddings (
    id INTEGER PRIMARY KEY AUTOINCREMENT,
    metadata_id INTEGER NOT NULL,
    embedding BLOB NOT NULL,
    UNIQUE(metadata_id),
    FOREIGN KEY (metadata_id) REFERENCES mcard_vector_metadata(id)
);

-- @virtual_table mcard_fts
-- @description Full-text search for hybrid retrieval
-- @note Uses Porter stemming with Unicode support
CREATE VIRTUAL TABLE IF NOT EXISTS mcard_fts USING fts5(
    hash,
    content,
    tokenize='porter unicode61'
);

-- Note: sqlite-vec virtual table is created dynamically with dimensions:
-- CREATE VIRTUAL TABLE IF NOT EXISTS mcard_vec USING vec0(
--     metadata_id INTEGER PRIMARY KEY,
--     embedding float[\${dimensions}]
-- );


-- ═══════════════════════════════════════════════════════════════════════════════
-- LAYER 4: SEMANTIC VERSIONING (Handle-Vector Bridge)
-- ═══════════════════════════════════════════════════════════════════════════════
-- Bridges handles to vector embeddings for semantic version comparison.
-- Enables measuring semantic drift between document versions.

-- @table handle_version_vectors
-- @description Links handle versions to their semantic embeddings
-- @column id                        - Auto-increment primary key
-- @column handle                    - FK to handle_registry.handle
-- @column hash                      - FK to card.hash (this version)
-- @column parent_hash               - FK to card.hash (previous version)
-- @column version_order             - 0 = current, 1 = previous, etc.
-- @column is_current                - TRUE if this is the current version
-- @column embedding_id              - FK to mcard_vector_metadata.id
-- @column semantic_delta_from_parent - Cosine similarity to parent [-1, 1]
-- @column upgrade_type              - Classification: 'trivial' | 'minor' | 'major' | 'breaking'
-- @column created_at                - When this version was linked
CREATE TABLE IF NOT EXISTS handle_version_vectors (
    id INTEGER PRIMARY KEY AUTOINCREMENT,
    handle TEXT NOT NULL,
    hash TEXT NOT NULL,
    parent_hash TEXT,
    version_order INTEGER NOT NULL,
    is_current BOOLEAN DEFAULT FALSE,
    embedding_id INTEGER,
    semantic_delta_from_parent REAL,
    upgrade_type TEXT,
    created_at TEXT NOT NULL,
    UNIQUE(handle, hash),
    FOREIGN KEY (embedding_id) REFERENCES mcard_vector_metadata(id)
);

-- @index idx_hvv_handle
-- @description Efficient lookup of versions by handle
CREATE INDEX IF NOT EXISTS idx_hvv_handle 
ON handle_version_vectors(handle);

-- @index idx_hvv_hash
-- @description Efficient lookup of versions by hash
CREATE INDEX IF NOT EXISTS idx_hvv_hash 
ON handle_version_vectors(hash);

-- @index idx_hvv_current
-- @description Efficient lookup of current versions
CREATE INDEX IF NOT EXISTS idx_hvv_current 
ON handle_version_vectors(is_current);

-- @index idx_hvv_parent
-- @description Efficient lookup by parent hash
CREATE INDEX IF NOT EXISTS idx_hvv_parent 
ON handle_version_vectors(parent_hash);

-- @table version_similarity_cache
-- @description Precomputed pairwise similarities for performance
-- @column id               - Auto-increment primary key
-- @column handle           - Handle these versions belong to
-- @column hash_a           - First version hash
-- @column hash_b           - Second version hash
-- @column similarity_score - Cosine similarity [-1, 1]
-- @column distance_euclidean - L2 distance [0, ∞)
-- @column computed_at      - When similarity was computed
CREATE TABLE IF NOT EXISTS version_similarity_cache (
    id INTEGER PRIMARY KEY AUTOINCREMENT,
    handle TEXT NOT NULL,
    hash_a TEXT NOT NULL,
    hash_b TEXT NOT NULL,
    similarity_score REAL NOT NULL,
    distance_euclidean REAL,
    computed_at TEXT NOT NULL,
    UNIQUE(handle, hash_a, hash_b)
);

-- @index idx_vsc_handle
-- @description Efficient lookup of cached similarities by handle
CREATE INDEX IF NOT EXISTS idx_vsc_handle 
ON version_similarity_cache(handle);


-- ═══════════════════════════════════════════════════════════════════════════════
-- LAYER 5: KNOWLEDGE GRAPH (GraphRAG)
-- ═══════════════════════════════════════════════════════════════════════════════
-- Storage for extracted knowledge graph entities and relationships.

-- @table graph_entities
-- @description Nodes in the knowledge graph
-- @column id          - Auto-increment primary key
-- @column name        - Entity name
-- @column type        - Entity type (e.g., "Person", "Organization")
-- @column description - Optional description
-- @column source_hash - FK to card.hash where entity was extracted
-- @column embedding   - Optional entity embedding
-- @column created_at  - When entity was created
CREATE TABLE IF NOT EXISTS graph_entities (
    id INTEGER PRIMARY KEY AUTOINCREMENT,
    name TEXT NOT NULL,
    type TEXT NOT NULL,
    description TEXT,
    source_hash TEXT NOT NULL,
    embedding BLOB,
    created_at TEXT NOT NULL,
    UNIQUE(name, type, source_hash)
);

-- @index idx_entity_name
-- @description Efficient entity lookup by name
CREATE INDEX IF NOT EXISTS idx_entity_name 
ON graph_entities(name);

-- @index idx_entity_type
-- @description Efficient entity lookup by type
CREATE INDEX IF NOT EXISTS idx_entity_type 
ON graph_entities(type);

-- @index idx_entity_source
-- @description Efficient entity lookup by source document
CREATE INDEX IF NOT EXISTS idx_entity_source 
ON graph_entities(source_hash);

-- @table graph_relationships
-- @description Edges in the knowledge graph
-- @column id               - Auto-increment primary key
-- @column source_entity_id - FK to graph_entities.id (from)
-- @column target_entity_id - FK to graph_entities.id (to)
-- @column relationship     - Relationship type/label
-- @column description      - Optional description
-- @column weight           - Relationship strength
-- @column source_hash      - FK to card.hash where relationship was extracted
-- @column created_at       - When relationship was created
CREATE TABLE IF NOT EXISTS graph_relationships (
    id INTEGER PRIMARY KEY AUTOINCREMENT,
    source_entity_id INTEGER NOT NULL,
    target_entity_id INTEGER NOT NULL,
    relationship TEXT NOT NULL,
    description TEXT,
    weight REAL DEFAULT 1.0,
    source_hash TEXT NOT NULL,
    created_at TEXT NOT NULL,
    UNIQUE(source_entity_id, target_entity_id, relationship, source_hash),
    FOREIGN KEY (source_entity_id) REFERENCES graph_entities(id),
    FOREIGN KEY (target_entity_id) REFERENCES graph_entities(id)
);

-- @index idx_rel_source
-- @description Efficient lookup of relationships by source entity
CREATE INDEX IF NOT EXISTS idx_rel_source 
ON graph_relationships(source_entity_id);

-- @index idx_rel_target
-- @description Efficient lookup of relationships by target entity
CREATE INDEX IF NOT EXISTS idx_rel_target 
ON graph_relationships(target_entity_id);

-- @table graph_communities
-- @description Hierarchical community summaries (GraphRAG)
-- @column id                  - Auto-increment primary key
-- @column level               - Hierarchy level (0 = leaf)
-- @column title               - Community title
-- @column summary             - AI-generated summary
-- @column embedding           - Community embedding
-- @column member_entity_ids   - JSON array of entity IDs
-- @column parent_community_id - FK to parent community
-- @column created_at          - When community was created
CREATE TABLE IF NOT EXISTS graph_communities (
    id INTEGER PRIMARY KEY AUTOINCREMENT,
    level INTEGER NOT NULL DEFAULT 0,
    title TEXT,
    summary TEXT NOT NULL,
    embedding BLOB,
    member_entity_ids TEXT,
    parent_community_id INTEGER,
    created_at TEXT NOT NULL,
    FOREIGN KEY (parent_community_id) REFERENCES graph_communities(id)
);

-- @index idx_community_level
-- @description Efficient lookup of communities by level
CREATE INDEX IF NOT EXISTS idx_community_level 
ON graph_communities(level);

-- @table graph_extractions
-- @description Tracks which documents have been processed for entity extraction
-- @column hash               - FK to card.hash (primary key)
-- @column entity_count       - Number of entities extracted
-- @column relationship_count - Number of relationships extracted
-- @column extracted_at       - When extraction was performed
CREATE TABLE IF NOT EXISTS graph_extractions (
    hash TEXT PRIMARY KEY,
    entity_count INTEGER DEFAULT 0,
    relationship_count INTEGER DEFAULT 0,
    extracted_at TEXT NOT NULL
);

-- ═══════════════════════════════════════════════════════════════════════════════
-- SCHEMA METADATA (Vector DB)
-- ═══════════════════════════════════════════════════════════════════════════════

-- @table schema_version
-- @description Tracks schema version for migrations
CREATE TABLE IF NOT EXISTS vector_schema_version (
    version TEXT PRIMARY KEY,
    applied_at TEXT NOT NULL,
    description TEXT
);

-- Insert current schema version
INSERT OR IGNORE INTO vector_schema_version (version, applied_at, description)
VALUES ('1.0.0', datetime('now'), 'Initial MCard Vector Schema');
`;
//# sourceMappingURL=schema_constants.js.map