@rkarim08/sia 1.0.0

package/migrations/semantic/001_initial.sql

@@ -0,0 +1,292 @@
+-- graph.db initial schema (ARCHI v4.1 section 2.4)
+-- Full bi-temporal model for entities and edges.
+
+-- -----------------------------------------------------------------
+-- ENTITIES
+-- Full bi-temporal model: both t_valid_from and t_valid_until apply
+-- to entities, not just to edges. When a Decision entity is
+-- superseded, it is invalidated (t_valid_until set) rather than
+-- soft-deleted (archived_at set). archived_at is reserved for
+-- low-importance entities that have simply decayed out of relevance.
+-- -----------------------------------------------------------------
+CREATE TABLE entities (
+  id               TEXT PRIMARY KEY,    -- UUID v4
+
+  -- Classification
+  type             TEXT NOT NULL,
+    -- 'CodeEntity' | 'Concept' | 'Decision' | 'Bug'
+    -- 'Solution' | 'Convention' | 'Community'
+  name             TEXT NOT NULL,
+  content          TEXT NOT NULL,       -- Full description (max ~500 words)
+  summary          TEXT NOT NULL,       -- One sentence (max 20 words)
+
+  -- Monorepo package scoping
+  package_path     TEXT,               -- e.g. 'packages/frontend'; NULL for standalone
+
+  -- Tags and file associations
+  tags             TEXT NOT NULL DEFAULT '[]',        -- JSON string[]
+  file_paths       TEXT NOT NULL DEFAULT '[]',        -- JSON string[] (relative paths)
+
+  -- Trust and confidence
+  trust_tier       INTEGER NOT NULL DEFAULT 3,
+    -- 1=UserDirect(x1.00) 2=CodeAnalysis(x0.90) 3=LLMInferred(x0.70) 4=External(x0.50)
+  confidence       REAL NOT NULL DEFAULT 0.7,
+  base_confidence  REAL NOT NULL DEFAULT 0.7,
+
+  -- Importance (retrieval ranking + decay)
+  importance       REAL NOT NULL DEFAULT 0.5,
+  base_importance  REAL NOT NULL DEFAULT 0.5,
+  access_count     INTEGER NOT NULL DEFAULT 0,
+  edge_count       INTEGER NOT NULL DEFAULT 0,    -- denormalized; maintained by trigger
+  last_accessed    INTEGER NOT NULL,              -- Unix ms
+  created_at       INTEGER NOT NULL,              -- Unix ms
+
+  -- *** FULL BI-TEMPORAL METADATA ON ENTITIES ***
+  t_created        INTEGER NOT NULL,   -- Unix ms: when Sia recorded this entity
+  t_expired        INTEGER,            -- Unix ms: when Sia invalidated it
+  t_valid_from     INTEGER,            -- Unix ms: when the fact became true in the world
+  t_valid_until    INTEGER,            -- Unix ms: when it stopped being true (NULL = still true)
+
+  -- Team visibility
+  visibility       TEXT NOT NULL DEFAULT 'private',   -- 'private' | 'team' | 'project'
+  created_by       TEXT NOT NULL,                     -- developer_id from sync_config
+  workspace_scope  TEXT,                              -- workspace_id when visibility='project'
+
+  -- Sync metadata
+  hlc_created      INTEGER,
+  hlc_modified     INTEGER,
+  synced_at        INTEGER,           -- NULL = not yet pushed to server
+
+  -- Conflict tracking
+  conflict_group_id TEXT,
+
+  -- Provenance
+  source_episode    TEXT,             -- episodic.episodes.id (cross-db ref, not enforced)
+  extraction_method TEXT,
+    -- 'tree-sitter' | 'spacy' | 'llm-haiku' | 'user-direct' | 'manifest'
+  extraction_model  TEXT,            -- model version string if LLM-extracted
+
+  -- Embedding (384-dim from all-MiniLM-L6-v2)
+  embedding        BLOB,
+
+  -- Soft delete for low-importance, disconnected, decayed entities
+  archived_at      INTEGER            -- NULL = active
+);
+
+-- -----------------------------------------------------------------
+-- FTS5 content table -- kept in sync via triggers
+-- -----------------------------------------------------------------
+CREATE VIRTUAL TABLE entities_fts USING fts5(
+  name, content, summary, tags,
+  content=entities,
+  content_rowid=rowid
+);
+
+-- Triggers to keep entities_fts in sync
+CREATE TRIGGER entities_ai AFTER INSERT ON entities BEGIN
+  INSERT INTO entities_fts(rowid, name, content, summary, tags)
+  VALUES (new.rowid, new.name, new.content, new.summary, new.tags);
+END;
+CREATE TRIGGER entities_ad AFTER DELETE ON entities BEGIN
+  INSERT INTO entities_fts(entities_fts, rowid, name, content, summary, tags)
+  VALUES ('delete', old.rowid, old.name, old.content, old.summary, old.tags);
+END;
+CREATE TRIGGER entities_au AFTER UPDATE ON entities BEGIN
+  INSERT INTO entities_fts(entities_fts, rowid, name, content, summary, tags)
+  VALUES ('delete', old.rowid, old.name, old.content, old.summary, old.tags);
+  INSERT INTO entities_fts(rowid, name, content, summary, tags)
+  VALUES (new.rowid, new.name, new.content, new.summary, new.tags);
+END;
+
+-- entities_vss (sqlite-vss) created at runtime when extension is loaded
+
+-- -----------------------------------------------------------------
+-- Entity indexes
+-- -----------------------------------------------------------------
+CREATE INDEX idx_entities_type       ON entities(type) WHERE archived_at IS NULL AND t_valid_until IS NULL;
+CREATE INDEX idx_entities_package    ON entities(package_path) WHERE archived_at IS NULL;
+CREATE INDEX idx_entities_importance ON entities(importance DESC) WHERE archived_at IS NULL AND t_valid_until IS NULL;
+CREATE INDEX idx_entities_trust      ON entities(trust_tier, confidence);
+CREATE INDEX idx_entities_visibility ON entities(visibility, synced_at);
+CREATE INDEX idx_entities_accessed   ON entities(last_accessed DESC);
+CREATE INDEX idx_entities_temporal   ON entities(t_valid_from, t_valid_until);
+CREATE INDEX idx_entities_conflict   ON entities(conflict_group_id) WHERE conflict_group_id IS NOT NULL;
+
+-- -----------------------------------------------------------------
+-- EDGES (bi-temporal, typed, weighted)
+-- -----------------------------------------------------------------
+CREATE TABLE edges (
+  id            TEXT PRIMARY KEY,
+  from_id       TEXT NOT NULL REFERENCES entities(id),
+  to_id         TEXT NOT NULL REFERENCES entities(id),
+  type          TEXT NOT NULL,
+    -- Structural (from AST):
+    --   'calls' | 'imports' | 'inherits_from' | 'contains' | 'depends_on'
+    -- Semantic (from LLM extraction):
+    --   'relates_to' | 'solves' | 'caused_by' | 'supersedes'
+    --   'elaborates' | 'contradicts' | 'used_in'
+    -- Community (from Leiden):
+    --   'member_of' | 'summarized_by'
+  weight        REAL NOT NULL DEFAULT 1.0,
+  confidence    REAL NOT NULL DEFAULT 0.7,
+  trust_tier    INTEGER NOT NULL DEFAULT 3,
+
+  -- Bi-temporal metadata
+  t_created     INTEGER NOT NULL,
+  t_expired     INTEGER,
+  t_valid_from  INTEGER,
+  t_valid_until INTEGER,            -- NULL = still active
+
+  -- Sync metadata
+  hlc_created   INTEGER,
+  hlc_modified  INTEGER,
+
+  source_episode    TEXT,
+  extraction_method TEXT
+);
+
+CREATE INDEX idx_edges_from     ON edges(from_id) WHERE t_valid_until IS NULL;
+CREATE INDEX idx_edges_to       ON edges(to_id)   WHERE t_valid_until IS NULL;
+CREATE INDEX idx_edges_type     ON edges(type);
+CREATE INDEX idx_edges_temporal ON edges(t_valid_from, t_valid_until);
+
+-- -----------------------------------------------------------------
+-- Edge count triggers
+-- -----------------------------------------------------------------
+
+-- Insert trigger: increment edge_count on both endpoints when a new active edge is created
+CREATE TRIGGER edges_ai_count AFTER INSERT ON edges
+  WHEN new.t_valid_until IS NULL
+BEGIN
+  UPDATE entities SET edge_count = edge_count + 1 WHERE id = new.from_id;
+  UPDATE entities SET edge_count = edge_count + 1 WHERE id = new.to_id;
+END;
+
+-- Invalidation trigger: decrement when edge goes from active -> invalidated
+CREATE TRIGGER edges_au_count_invalidate
+  AFTER UPDATE OF t_valid_until ON edges
+  WHEN old.t_valid_until IS NULL AND new.t_valid_until IS NOT NULL
+BEGIN
+  UPDATE entities SET edge_count = edge_count - 1 WHERE id = new.from_id;
+  UPDATE entities SET edge_count = edge_count - 1 WHERE id = new.to_id;
+END;
+
+-- Reactivation trigger: increment when edge goes from invalidated -> active
+CREATE TRIGGER edges_au_count_reactivate
+  AFTER UPDATE OF t_valid_until ON edges
+  WHEN old.t_valid_until IS NOT NULL AND new.t_valid_until IS NULL
+BEGIN
+  UPDATE entities SET edge_count = edge_count + 1 WHERE id = new.from_id;
+  UPDATE entities SET edge_count = edge_count + 1 WHERE id = new.to_id;
+END;
+
+-- -----------------------------------------------------------------
+-- COMMUNITIES AND SUMMARY TREE
+-- -----------------------------------------------------------------
+CREATE TABLE communities (
+  id                        TEXT PRIMARY KEY,
+  level                     INTEGER NOT NULL,    -- 0=fine, 1=medium, 2=coarse
+  parent_id                 TEXT REFERENCES communities(id),
+  summary                   TEXT,
+  summary_hash              TEXT,                -- SHA-256 of sorted member entity IDs
+  member_count              INTEGER DEFAULT 0,
+  last_summary_member_count INTEGER DEFAULT 0,  -- member_count at time of last summary generation
+  package_path              TEXT,               -- NULL=whole repo; set=monorepo package
+  created_at                INTEGER NOT NULL,
+  updated_at                INTEGER NOT NULL
+);
+
+CREATE TABLE community_members (
+  community_id TEXT NOT NULL REFERENCES communities(id),
+  entity_id    TEXT NOT NULL REFERENCES entities(id),
+  level        INTEGER NOT NULL,
+  PRIMARY KEY (community_id, entity_id)
+);
+
+CREATE TABLE summary_tree (
+  id           TEXT PRIMARY KEY,
+  level        INTEGER NOT NULL,   -- 0=raw entity, 1=entity summary, 2=module, 3=architectural
+  scope_id     TEXT NOT NULL,      -- entity_id (levels 0-1) | community_id (levels 2-3)
+  content      TEXT NOT NULL,
+  content_hash TEXT NOT NULL,
+  token_count  INTEGER NOT NULL,
+  created_at   INTEGER NOT NULL,
+  expires_at   INTEGER             -- NULL = valid; set when source facts change
+);
+
+-- -----------------------------------------------------------------
+-- SECURITY STAGING
+-- Physically isolated: no FK relationships to entities or edges.
+-- -----------------------------------------------------------------
+CREATE TABLE memory_staging (
+  id                   TEXT PRIMARY KEY,
+  source_episode       TEXT,
+  proposed_type        TEXT NOT NULL,
+  proposed_name        TEXT NOT NULL,
+  proposed_content     TEXT NOT NULL,
+  proposed_tags        TEXT NOT NULL DEFAULT '[]',
+  proposed_file_paths  TEXT NOT NULL DEFAULT '[]',
+  trust_tier           INTEGER NOT NULL DEFAULT 4,
+  raw_confidence       REAL NOT NULL,
+  validation_status    TEXT NOT NULL DEFAULT 'pending',
+    -- 'pending' | 'passed' | 'rejected' | 'quarantined'
+  rejection_reason     TEXT,
+  created_at           INTEGER NOT NULL,
+  expires_at           INTEGER NOT NULL  -- created_at + (7 * 86400000)
+);
+
+-- -----------------------------------------------------------------
+-- SESSION FLAGS AND AUDIT LOG
+-- -----------------------------------------------------------------
+CREATE TABLE session_flags (
+  id                  TEXT PRIMARY KEY,
+  session_id          TEXT NOT NULL,
+  reason              TEXT NOT NULL,        -- sanitized, max 100 chars
+  transcript_position INTEGER,
+  created_at          INTEGER NOT NULL,
+  consumed            INTEGER NOT NULL DEFAULT 0   -- 1 = pipeline processed this flag
+);
+CREATE INDEX idx_flags_session ON session_flags(session_id, consumed);
+
+CREATE TABLE audit_log (
+  id               TEXT PRIMARY KEY,
+  ts               INTEGER NOT NULL,
+  hlc              INTEGER,
+  operation        TEXT NOT NULL,
+    -- 'ADD' | 'UPDATE' | 'INVALIDATE' | 'NOOP'
+    -- 'STAGE' | 'PROMOTE' | 'QUARANTINE'
+    -- 'SYNC_RECV' | 'SYNC_SEND'
+    -- 'ARCHIVE' | 'VSS_REFRESH'
+  entity_id        TEXT,
+  edge_id          TEXT,
+  source_episode   TEXT,
+  trust_tier       INTEGER,
+  extraction_method TEXT,
+  source_hash      TEXT,                    -- SHA-256 of raw source content
+  developer_id     TEXT,
+  snapshot_id      TEXT
+);
+
+-- -----------------------------------------------------------------
+-- DEDUPLICATION LOGS
+-- Two separate tables for two separate processes (Issue #21).
+-- -----------------------------------------------------------------
+
+-- local_dedup_log: nightly consolidation sweep (intra-developer, local graph only)
+CREATE TABLE local_dedup_log (
+  entity_a_id TEXT NOT NULL,
+  entity_b_id TEXT NOT NULL,
+  decision    TEXT NOT NULL,   -- 'merged' | 'different' | 'related' | 'pending'
+  checked_at  INTEGER NOT NULL,
+  PRIMARY KEY (entity_a_id, entity_b_id)
+);
+
+-- sync_dedup_log: post-sync deduplication (cross-developer; peer_id disambiguates source)
+CREATE TABLE sync_dedup_log (
+  entity_a_id  TEXT NOT NULL,   -- local entity
+  entity_b_id  TEXT NOT NULL,   -- peer entity
+  peer_id      TEXT NOT NULL,   -- which teammate this came from
+  decision     TEXT NOT NULL,   -- 'merged' | 'different' | 'related' | 'pending'
+  checked_at   INTEGER NOT NULL,
+  PRIMARY KEY (entity_a_id, entity_b_id, peer_id)
+);

package/migrations/semantic/002_ontology.sql

@@ -0,0 +1,89 @@
+-- Migration: 002_ontology.sql
+-- Ontology Constraint Layer
+-- Adds the edge_constraints metadata table declaring all valid (source_type, edge_type, target_type) triples.
+-- Application-layer middleware uses this table to validate edges before insertion.
+
+CREATE TABLE IF NOT EXISTS edge_constraints (
+  id          INTEGER PRIMARY KEY AUTOINCREMENT,
+  source_type TEXT NOT NULL,
+  edge_type   TEXT NOT NULL,
+  target_type TEXT NOT NULL,
+  description TEXT,
+  cardinality TEXT DEFAULT 'many-to-many',
+  required    INTEGER DEFAULT 0,
+  UNIQUE(source_type, edge_type, target_type)
+);
+
+-- Seed the constraints table with all valid triples from the Sia v5 ontology.
+
+-- Structural edges
+INSERT OR IGNORE INTO edge_constraints (source_type, edge_type, target_type, description) VALUES
+  ('FileNode',    'defines',       'CodeEntity',  'File defines a function/class/module'),
+  ('CodeEntity',  'imports',       'CodeEntity',  'Symbol imports another symbol'),
+  ('CodeEntity',  'calls',         'CodeEntity',  'Symbol calls another symbol'),
+  ('CodeEntity',  'inherits_from', 'CodeEntity',  'Class inherits from parent'),
+  ('PackageNode', 'contains',      'FileNode',    'Package contains file'),
+  ('PackageNode', 'depends_on',    'PackageNode', 'Package depends on another package'),
+  ('Community',   'contains',      'CodeEntity',  'Community contains symbol'),
+  ('Community',   'contains',      'FileNode',    'Community contains file');
+
+-- Semantic edges
+INSERT OR IGNORE INTO edge_constraints (source_type, edge_type, target_type, description) VALUES
+  ('Decision',    'pertains_to',  'CodeEntity',  'Decision concerns a code symbol'),
+  ('Decision',    'pertains_to',  'FileNode',    'Decision concerns a file'),
+  ('Decision',    'pertains_to',  'PackageNode', 'Decision concerns a package'),
+  ('Convention',  'pertains_to',  'CodeEntity',  'Convention governs a code symbol'),
+  ('Convention',  'pertains_to',  'FileNode',    'Convention governs a file'),
+  ('Convention',  'pertains_to',  'PackageNode', 'Convention governs a package'),
+  ('Bug',         'caused_by',    'CodeEntity',  'Bug caused by a code symbol'),
+  ('Bug',         'caused_by',    'FileNode',    'Bug caused by code in a file'),
+  ('Solution',    'solves',       'Bug',         'Solution resolves a bug'),
+  ('Solution',    'pertains_to',  'CodeEntity',  'Solution modifies a code symbol'),
+  ('Solution',    'pertains_to',  'FileNode',    'Solution modifies a file'),
+  ('Concept',     'pertains_to',  'CodeEntity',  'Concept relates to a symbol'),
+  ('Concept',     'pertains_to',  'FileNode',    'Concept relates to a file'),
+  ('Concept',     'pertains_to',  'PackageNode', 'Concept relates to a package'),
+  ('Concept',     'elaborates',   'Decision',    'Concept elaborates a decision'),
+  ('Decision',    'elaborates',   'Convention',  'Decision elaborates a convention');
+
+-- Supersession edges (same-type only — enforced at application layer)
+INSERT OR IGNORE INTO edge_constraints (source_type, edge_type, target_type, description) VALUES
+  ('Decision',    'supersedes',   'Decision',    'New decision supersedes old'),
+  ('Convention',  'supersedes',   'Convention',  'New convention supersedes old'),
+  ('Solution',    'supersedes',   'Solution',    'New solution supersedes old'),
+  ('Concept',     'supersedes',   'Concept',     'New concept supersedes old');
+
+-- Contradiction edges
+INSERT OR IGNORE INTO edge_constraints (source_type, edge_type, target_type, description) VALUES
+  ('Decision',    'contradicts',  'Decision',    'Two decisions contradict'),
+  ('Convention',  'contradicts',  'Convention',  'Two conventions contradict');
+
+-- Generic relationship edges (used by capture pipeline and consolidation)
+INSERT OR IGNORE INTO edge_constraints (source_type, edge_type, target_type, description) VALUES
+  ('Concept',     'relates_to',   'Concept',     'Concept relates to concept'),
+  ('Concept',     'relates_to',   'CodeEntity',  'Concept relates to code'),
+  ('Concept',     'relates_to',   'FileNode',    'Concept relates to file'),
+  ('Decision',    'relates_to',   'Decision',    'Decision relates to decision'),
+  ('Decision',    'relates_to',   'CodeEntity',  'Decision relates to code'),
+  ('Convention',  'relates_to',   'Convention',  'Convention relates to convention'),
+  ('Bug',         'relates_to',   'Bug',         'Bug relates to bug'),
+  ('Bug',         'relates_to',   'CodeEntity',  'Bug relates to code'),
+  ('Solution',    'relates_to',   'CodeEntity',  'Solution relates to code'),
+  ('CodeEntity',  'relates_to',   'CodeEntity',  'Code symbol relates to another'),
+  ('FileNode',    'relates_to',   'FileNode',    'File relates to file'),
+  ('Dependency',  'relates_to',   'CodeEntity',  'Dependency relates to code');
+
+-- Documentation edges (Phase 14 additions)
+INSERT OR IGNORE INTO edge_constraints (source_type, edge_type, target_type, description) VALUES
+  ('ContentChunk', 'child_of',     'FileNode',    'Chunk belongs to document'),
+  ('FileNode',     'references',   'FileNode',    'Document links to another document'),
+  ('ContentChunk', 'references',   'CodeEntity',  'Chunk mentions a code symbol'),
+  ('ContentChunk', 'references',   'FileNode',    'Chunk mentions a file'),
+  ('ContentChunk', 'references',   'Decision',    'Chunk references a decision'),
+  ('ContentChunk', 'references',   'Convention',  'Chunk references a convention');
+
+-- Community membership edges
+INSERT OR IGNORE INTO edge_constraints (source_type, edge_type, target_type, description) VALUES
+  ('CodeEntity',   'member_of',      'Community',     'Symbol belongs to community'),
+  ('FileNode',     'member_of',      'Community',     'File belongs to community'),
+  ('Community',    'summarized_by',  'ContentChunk',  'Community summarized by chunk');

package/migrations/semantic/003_freshness.sql

@@ -0,0 +1,63 @@
+-- Phase 15: Freshness Engine — source_deps inverted index + current_entities shadow table
+
+-- Maps each source file to every graph node derived from it.
+-- When file X changes, SELECT node_id FROM source_deps WHERE source_path = X
+-- returns the exact set of nodes that may be stale.
+CREATE TABLE IF NOT EXISTS source_deps (
+  source_path  TEXT NOT NULL,
+  node_id      TEXT NOT NULL REFERENCES entities(id),
+  dep_type     TEXT NOT NULL,
+  source_mtime INTEGER NOT NULL,
+  PRIMARY KEY (source_path, node_id)
+);
+
+CREATE INDEX IF NOT EXISTS idx_source_deps_path ON source_deps(source_path);
+CREATE INDEX IF NOT EXISTS idx_source_deps_node ON source_deps(node_id);
+
+-- Shadow table: contains ONLY active, non-archived entities.
+-- Eliminates the temporal predicate from the most common query pattern.
+CREATE TABLE IF NOT EXISTS current_entities AS
+  SELECT * FROM entities
+  WHERE t_valid_until IS NULL AND archived_at IS NULL;
+
+CREATE INDEX IF NOT EXISTS idx_current_type ON current_entities(type);
+CREATE INDEX IF NOT EXISTS idx_current_importance ON current_entities(importance DESC);
+
+-- Shadow maintenance triggers
+CREATE TRIGGER IF NOT EXISTS shadow_invalidate
+  AFTER UPDATE OF t_valid_until ON entities
+  WHEN new.t_valid_until IS NOT NULL AND old.t_valid_until IS NULL
+BEGIN
+  DELETE FROM current_entities WHERE id = new.id;
+END;
+
+CREATE TRIGGER IF NOT EXISTS shadow_archive
+  AFTER UPDATE OF archived_at ON entities
+  WHEN new.archived_at IS NOT NULL AND old.archived_at IS NULL
+BEGIN
+  DELETE FROM current_entities WHERE id = new.id;
+END;
+
+CREATE TRIGGER IF NOT EXISTS shadow_insert
+  AFTER INSERT ON entities
+  WHEN new.t_valid_until IS NULL AND new.archived_at IS NULL
+BEGIN
+  INSERT INTO current_entities SELECT * FROM entities WHERE id = new.id;
+END;
+
+CREATE TRIGGER IF NOT EXISTS shadow_reactivate
+  AFTER UPDATE OF t_valid_until ON entities
+  WHEN new.t_valid_until IS NULL AND old.t_valid_until IS NOT NULL
+BEGIN
+  INSERT OR REPLACE INTO current_entities SELECT * FROM entities WHERE id = new.id;
+END;
+
+-- Partial indexes for hot-path queries
+CREATE INDEX IF NOT EXISTS idx_entities_type_active ON entities(type)
+  WHERE archived_at IS NULL AND t_valid_until IS NULL;
+CREATE INDEX IF NOT EXISTS idx_entities_importance_active ON entities(importance DESC)
+  WHERE archived_at IS NULL AND t_valid_until IS NULL;
+CREATE INDEX IF NOT EXISTS idx_edges_from_active ON edges(from_id)
+  WHERE t_valid_until IS NULL;
+CREATE INDEX IF NOT EXISTS idx_edges_to_active ON edges(to_id)
+  WHERE t_valid_until IS NULL;

package/migrations/semantic/004_v5_unified_schema.sql

@@ -0,0 +1,194 @@
+-- Migration: 004_v5_unified_schema.sql
+-- Rename entities->graph_nodes and edges->graph_edges,
+-- add v5 columns, session tables, and rebuild FTS5 + triggers.
+
+-- -----------------------------------------------------------------
+-- Step A: Rename tables
+-- -----------------------------------------------------------------
+ALTER TABLE entities RENAME TO graph_nodes;
+ALTER TABLE edges RENAME TO graph_edges;
+
+-- -----------------------------------------------------------------
+-- Step B: Add new v5 columns to graph_nodes
+-- -----------------------------------------------------------------
+ALTER TABLE graph_nodes ADD COLUMN kind TEXT;
+ALTER TABLE graph_nodes ADD COLUMN priority_tier INTEGER DEFAULT 3;
+ALTER TABLE graph_nodes ADD COLUMN session_id TEXT;
+ALTER TABLE graph_nodes ADD COLUMN properties TEXT DEFAULT '{}';
+
+-- -----------------------------------------------------------------
+-- Step C: Backfill kind from type
+-- -----------------------------------------------------------------
+UPDATE graph_nodes SET kind = type WHERE kind IS NULL;
+
+-- -----------------------------------------------------------------
+-- Step D: Add session_resume table
+-- -----------------------------------------------------------------
+CREATE TABLE IF NOT EXISTS session_resume (
+  session_id    TEXT PRIMARY KEY,
+  subgraph_json TEXT NOT NULL,
+  last_prompt   TEXT,
+  budget_used   INTEGER DEFAULT 0,
+  created_at    INTEGER NOT NULL,
+  updated_at    INTEGER NOT NULL
+);
+
+-- -----------------------------------------------------------------
+-- Step E: Add search_throttle table
+-- -----------------------------------------------------------------
+CREATE TABLE IF NOT EXISTS search_throttle (
+  session_id   TEXT NOT NULL,
+  tool_name    TEXT NOT NULL,
+  call_count   INTEGER NOT NULL DEFAULT 1,
+  last_called_at INTEGER NOT NULL,
+  PRIMARY KEY (session_id, tool_name)
+);
+
+-- -----------------------------------------------------------------
+-- Step F: Add DELETE edge_count trigger
+-- -----------------------------------------------------------------
+CREATE TRIGGER IF NOT EXISTS trg_edge_count_delete
+  AFTER DELETE ON graph_edges
+  WHEN OLD.t_valid_until IS NULL
+BEGIN
+  UPDATE graph_nodes SET edge_count = MAX(0, edge_count - 1) WHERE id = OLD.from_id;
+  UPDATE graph_nodes SET edge_count = MAX(0, edge_count - 1) WHERE id = OLD.to_id;
+END;
+
+-- -----------------------------------------------------------------
+-- Step G: Recreate FTS5 for graph_nodes
+-- Drop old FTS5 triggers first (they reference 'entities')
+-- -----------------------------------------------------------------
+DROP TRIGGER IF EXISTS entities_ai;
+DROP TRIGGER IF EXISTS entities_ad;
+DROP TRIGGER IF EXISTS entities_au;
+
+-- Drop old FTS5 virtual table
+DROP TABLE IF EXISTS entities_fts;
+
+-- Create new FTS5 for graph_nodes
+CREATE VIRTUAL TABLE graph_nodes_fts USING fts5(
+  name, content, summary, tags,
+  content='graph_nodes',
+  content_rowid='rowid'
+);
+
+-- Rebuild FTS from existing data
+INSERT INTO graph_nodes_fts(graph_nodes_fts) VALUES ('rebuild');
+
+-- New FTS sync triggers
+CREATE TRIGGER graph_nodes_fts_ai AFTER INSERT ON graph_nodes BEGIN
+  INSERT INTO graph_nodes_fts(rowid, name, content, summary, tags)
+  VALUES (NEW.rowid, NEW.name, NEW.content, NEW.summary, NEW.tags);
+END;
+
+CREATE TRIGGER graph_nodes_fts_ad AFTER DELETE ON graph_nodes BEGIN
+  INSERT INTO graph_nodes_fts(graph_nodes_fts, rowid, name, content, summary, tags)
+  VALUES ('delete', OLD.rowid, OLD.name, OLD.content, OLD.summary, OLD.tags);
+END;
+
+CREATE TRIGGER graph_nodes_fts_au AFTER UPDATE ON graph_nodes BEGIN
+  INSERT INTO graph_nodes_fts(graph_nodes_fts, rowid, name, content, summary, tags)
+  VALUES ('delete', OLD.rowid, OLD.name, OLD.content, OLD.summary, OLD.tags);
+  INSERT INTO graph_nodes_fts(rowid, name, content, summary, tags)
+  VALUES (NEW.rowid, NEW.name, NEW.content, NEW.summary, NEW.tags);
+END;
+
+-- -----------------------------------------------------------------
+-- Step H: Recreate edge_count triggers for graph_nodes/graph_edges
+-- Drop old triggers that reference 'entities'/'edges'
+-- -----------------------------------------------------------------
+DROP TRIGGER IF EXISTS edges_ai_count;
+DROP TRIGGER IF EXISTS edges_au_count_invalidate;
+DROP TRIGGER IF EXISTS edges_au_count_reactivate;
+DROP TRIGGER IF EXISTS trg_edge_count_insert;
+DROP TRIGGER IF EXISTS trg_edge_count_invalidate;
+DROP TRIGGER IF EXISTS trg_edge_count_reactivate;
+
+CREATE TRIGGER trg_edge_count_insert AFTER INSERT ON graph_edges
+  WHEN NEW.t_valid_until IS NULL
+BEGIN
+  UPDATE graph_nodes SET edge_count = edge_count + 1 WHERE id = NEW.from_id;
+  UPDATE graph_nodes SET edge_count = edge_count + 1 WHERE id = NEW.to_id;
+END;
+
+CREATE TRIGGER trg_edge_count_invalidate AFTER UPDATE OF t_valid_until ON graph_edges
+  WHEN OLD.t_valid_until IS NULL AND NEW.t_valid_until IS NOT NULL
+BEGIN
+  UPDATE graph_nodes SET edge_count = MAX(0, edge_count - 1) WHERE id = NEW.from_id;
+  UPDATE graph_nodes SET edge_count = MAX(0, edge_count - 1) WHERE id = NEW.to_id;
+END;
+
+CREATE TRIGGER trg_edge_count_reactivate AFTER UPDATE OF t_valid_until ON graph_edges
+  WHEN OLD.t_valid_until IS NOT NULL AND NEW.t_valid_until IS NULL
+BEGIN
+  UPDATE graph_nodes SET edge_count = edge_count + 1 WHERE id = NEW.from_id;
+  UPDATE graph_nodes SET edge_count = edge_count + 1 WHERE id = NEW.to_id;
+END;
+
+-- -----------------------------------------------------------------
+-- Step I: Drop and recreate triggers from 003_freshness.sql that
+-- reference the old 'entities' table name.
+-- Also fix the source_deps FK reference and current_entities shadow.
+-- -----------------------------------------------------------------
+
+-- Drop old shadow maintenance triggers (they reference 'entities')
+DROP TRIGGER IF EXISTS shadow_invalidate;
+DROP TRIGGER IF EXISTS shadow_archive;
+DROP TRIGGER IF EXISTS shadow_insert;
+DROP TRIGGER IF EXISTS shadow_reactivate;
+
+-- Drop old current_entities shadow table (was built from entities)
+DROP TABLE IF EXISTS current_entities;
+
+-- Drop old source_deps (FK referenced entities(id), now graph_nodes)
+DROP TABLE IF EXISTS source_deps;
+
+-- Recreate source_deps referencing graph_nodes
+CREATE TABLE IF NOT EXISTS source_deps (
+  source_path  TEXT NOT NULL,
+  node_id      TEXT NOT NULL REFERENCES graph_nodes(id),
+  dep_type     TEXT NOT NULL,
+  source_mtime INTEGER NOT NULL,
+  PRIMARY KEY (source_path, node_id)
+);
+
+CREATE INDEX IF NOT EXISTS idx_source_deps_path ON source_deps(source_path);
+CREATE INDEX IF NOT EXISTS idx_source_deps_node ON source_deps(node_id);
+
+-- Recreate current_entities shadow as current_nodes from graph_nodes
+CREATE TABLE IF NOT EXISTS current_nodes AS
+  SELECT * FROM graph_nodes
+  WHERE t_valid_until IS NULL AND archived_at IS NULL;
+
+CREATE INDEX IF NOT EXISTS idx_current_type ON current_nodes(type);
+CREATE INDEX IF NOT EXISTS idx_current_importance ON current_nodes(importance DESC);
+
+-- Recreate shadow maintenance triggers referencing graph_nodes / current_nodes
+CREATE TRIGGER IF NOT EXISTS shadow_invalidate
+  AFTER UPDATE OF t_valid_until ON graph_nodes
+  WHEN NEW.t_valid_until IS NOT NULL AND OLD.t_valid_until IS NULL
+BEGIN
+  DELETE FROM current_nodes WHERE id = NEW.id;
+END;
+
+CREATE TRIGGER IF NOT EXISTS shadow_archive
+  AFTER UPDATE OF archived_at ON graph_nodes
+  WHEN NEW.archived_at IS NOT NULL AND OLD.archived_at IS NULL
+BEGIN
+  DELETE FROM current_nodes WHERE id = NEW.id;
+END;
+
+CREATE TRIGGER IF NOT EXISTS shadow_insert
+  AFTER INSERT ON graph_nodes
+  WHEN NEW.t_valid_until IS NULL AND NEW.archived_at IS NULL
+BEGIN
+  INSERT INTO current_nodes SELECT * FROM graph_nodes WHERE id = NEW.id;
+END;
+
+CREATE TRIGGER IF NOT EXISTS shadow_reactivate
+  AFTER UPDATE OF t_valid_until ON graph_nodes
+  WHEN NEW.t_valid_until IS NULL AND OLD.t_valid_until IS NOT NULL
+BEGIN
+  INSERT OR REPLACE INTO current_nodes SELECT * FROM graph_nodes WHERE id = NEW.id;
+END;

package/migrations/semantic/005_backfill_event_kinds.sql

@@ -0,0 +1,8 @@
+-- Migration 005: Backfill event node kinds
+-- Reclassifies existing CodeEntity nodes whose names follow event prefixes
+-- into purpose-specific kind values for better semantic retrieval.
+
+UPDATE graph_nodes SET kind = 'EditEvent' WHERE kind = 'CodeEntity' AND name LIKE 'Edit: %';
+UPDATE graph_nodes SET kind = 'ExecutionEvent' WHERE kind = 'CodeEntity' AND name LIKE 'Bash: %';
+UPDATE graph_nodes SET kind = 'GitEvent' WHERE kind = 'CodeEntity' AND name LIKE 'Git: %';
+UPDATE graph_nodes SET kind = 'ErrorEvent' WHERE kind = 'CodeEntity' AND name LIKE 'Error: %';

package/migrations/semantic/006_tree_sitter.sql

@@ -0,0 +1,6 @@
+-- Migration 006: tree-sitter extraction backend tracking
+-- Note: entities was renamed to graph_nodes in migration 004.
+-- current_nodes is a shadow table maintained by triggers (SELECT * FROM graph_nodes),
+-- so it must also get the new column to keep column counts in sync.
+ALTER TABLE graph_nodes ADD COLUMN extraction_backend TEXT;
+ALTER TABLE current_nodes ADD COLUMN extraction_backend TEXT;

package/migrations/semantic/007_branch_snapshots.sql

@@ -0,0 +1,22 @@
+-- Migration 007: branch-keyed snapshots for fast branch switching
+--
+-- Stores graph snapshots per branch so that switching back to a
+-- previously-analyzed branch restores its state without a full rebuild.
+-- Each branch gets exactly one snapshot (UPSERT on branch_name).
+
+CREATE TABLE IF NOT EXISTS branch_snapshots (
+    id INTEGER PRIMARY KEY AUTOINCREMENT,
+    branch_name TEXT NOT NULL UNIQUE,
+    commit_hash TEXT NOT NULL,
+    node_count INTEGER NOT NULL DEFAULT 0,
+    edge_count INTEGER NOT NULL DEFAULT 0,
+    snapshot_data TEXT NOT NULL,
+    created_at INTEGER NOT NULL DEFAULT (unixepoch() * 1000),
+    updated_at INTEGER NOT NULL DEFAULT (unixepoch() * 1000)
+);
+
+CREATE INDEX IF NOT EXISTS idx_branch_snapshots_branch
+    ON branch_snapshots(branch_name);
+
+CREATE INDEX IF NOT EXISTS idx_branch_snapshots_updated
+    ON branch_snapshots(updated_at);