fix: health check — schema migrations, import crash, error handling, performance

- Add lightweight schema migration system using PRAGMA user_version
- Fix dashboard import crash by routing through MCP server
- Replace silent contextlib.suppress(Exception) with logged warnings
- Add column allowlist in ContentStore.update() to prevent injection
- Surface graph/SQLite sync failures via SyncError instead of swallowing
- Fix XSS in dashboard search with html.escape
- Fix O(n) entity name scan with SPARQL LCASE() filter
- Fix semantic search loading all embeddings without error handling
- Add count_entities() to avoid materializing full list for counts
- Align Dockerfile to Python 3.13 (matches CI), remove error suppression
- Remove unused aiosqlite dependency
- Fix stale REST API version (now reads __version__)
- Bump version to 0.3.2

Author: grayisnotacolor

Dockerfile

@@ -1,4 +1,4 @@
-FROM python:3.12-slim AS base
+FROM python:3.13-slim AS base
 
 WORKDIR /app
 
@@ -17,7 +17,7 @@ COPY ontology/ ontology/
 COPY llms.txt ./
 
 # Install dependencies (including embeddings for semantic search)
-RUN uv sync --no-dev --frozen --extra embeddings 2>/dev/null || uv sync --no-dev --extra embeddings
+RUN uv sync --no-dev --frozen --extra embeddings
 
 # Create data directory and initialize
 RUN mkdir -p /data
@@ -33,4 +33,4 @@ HEALTHCHECK --interval=30s --timeout=5s --start-period=30s \
     CMD python -c "import urllib.request,json; r=urllib.request.Request('http://localhost:1314/mcp',data=json.dumps({'jsonrpc':'2.0','id':1,'method':'ping'}).encode(),headers={'Content-Type':'application/json','Accept':'application/json, text/event-stream'},method='POST'); urllib.request.urlopen(r)" || exit 1
 
 # Setup (auto mode: writes .env from env vars, inits stores), then start server
-CMD ["sh", "-c", "uv run cortex setup --auto 2>/dev/null; uv run cortex serve --transport mcp-http --host 0.0.0.0 --port 1314"]
+CMD ["sh", "-c", "uv run cortex setup --auto && uv run cortex serve --transport mcp-http --host 0.0.0.0 --port 1314"]

pyproject.toml

@@ -1,6 +1,6 @@
 [project]
 name = "abbacus-cortex"
-version = "0.3.1"
+version = "0.3.2"
 description = "Cognitive knowledge system with formal ontology, reasoning, and intelligence serving"
 readme = "README.md"
 authors = [
@@ -26,8 +26,6 @@ classifiers = [
 dependencies = [
     # Graph / Ontology
     "pyoxigraph>=0.4",
-    # SQLite (async)
-    "aiosqlite>=0.20",
     # Web framework
     "fastapi>=0.115",
     "uvicorn[standard]>=0.34",

src/cortex/__init__.py

@@ -1,3 +1,3 @@
 """Cortex — Cognitive knowledge system."""
 
-__version__ = "0.3.1"
+__version__ = "0.3.2"

src/cortex/dashboard/server.py

@@ -13,6 +13,7 @@
 
 from __future__ import annotations
 
+import html as html_mod
 import secrets
 from pathlib import Path
 from typing import Any
@@ -482,14 +483,7 @@ async def settings_import(request: Request, vault_path: str = Form(...)):
             )
 
         try:
-            import cortex.db.store as _store_mod
-            import cortex.pipeline.importer as _importer_mod
-
-            store = _store_mod.Store(config.data_dir)
-            importer = _importer_mod.ObsidianImporter(store, pipeline=None)
-            result = importer.run(vault)
-            store.close()
-
+            result = await mcp_client.import_obsidian(str(vault))
             imported = result.get("imported", 0)
             skipped = result.get("skipped", 0)
             failed = result.get("failed", 0)
@@ -923,21 +917,22 @@ async def api_search(request: Request, q: str = ""):
             return HTMLResponse("")
         results = await mcp_client.search(q, limit=8)
         # Return HTML fragment for HTMX
-        html = ""
+        html_out = ""
         for doc in results:
-            obj_id = doc.get("id", "")
-            title = doc.get("title", obj_id[:12])
-            doc_type = doc.get("type", "")
-            html += (
+            obj_id = html_mod.escape(doc.get("id", ""), quote=True)
+            title = html_mod.escape(doc.get("title", obj_id[:12]), quote=True)
+            doc_type = html_mod.escape(doc.get("type", ""), quote=True)
+            html_out += (
                 f'<div class="search-item" '
-                f"onclick=\"document.getElementById('target_id').value='{obj_id}'; "
+                f'data-id="{obj_id}" '
+                f"onclick=\"document.getElementById('target_id').value=this.dataset.id; "
                 f"document.getElementById('search-results').innerHTML='';\">"
                 f'<span class="badge badge-{doc_type}" style="font-size:0.7rem;">{doc_type}</span> '
                 f"{title[:60]}"
                 f'<small style="color:var(--text-muted);"> {obj_id[:8]}</small>'
                 f"</div>"
             )
-        return HTMLResponse(html)
+        return HTMLResponse(html_out)
 
     @app.post("/api/feedback")
     async def api_feedback(request: Request):

src/cortex/db/content_store.py

@@ -1,13 +1,14 @@
 """SQLite-backed content store for Cortex.
 
 Handles content storage, FTS5 full-text search, config, and query logging.
-Uses synchronous sqlite3 (async wrapper can be added later via aiosqlite).
+Uses synchronous sqlite3.
 """
 
 from __future__ import annotations
 
 import json
 import sqlite3
+from collections.abc import Callable
 from datetime import UTC, datetime
 from pathlib import Path
 from typing import Any
@@ -99,6 +100,33 @@
 CREATE INDEX IF NOT EXISTS idx_query_log_timestamp ON query_log(timestamp);
 """
 
+# Columns that callers may update via ContentStore.update().
+# When a migration adds a new column, add it here too.
+UPDATABLE_COLUMNS: frozenset[str] = frozenset({
+    "title",
+    "content",
+    "raw_markdown",
+    "type",
+    "project",
+    "tags",
+    "summary",
+    "tier",
+    "pipeline_stage",
+    "confidence",
+    "captured_by",
+    "updated_at",
+})
+
+_IMMUTABLE_COLUMNS: frozenset[str] = frozenset({"id", "created_at"})
+
+# Schema versioning — bump SCHEMA_VERSION and add a migration function
+# when the schema changes. See MIGRATIONS below.
+SCHEMA_VERSION = 1
+
+# List of (target_version, migration_function) tuples.
+# Each function receives a sqlite3.Connection and mutates the schema.
+MIGRATIONS: list[tuple[int, Callable[[sqlite3.Connection], None]]] = []
+
 
 class ContentStore:
     """SQLite store for document content, FTS5 search, config, and query logs."""
@@ -121,8 +149,32 @@ def __init__(self, path: Path | None = None):
         self._init_schema()
 
     def _init_schema(self) -> None:
-        self._db.executescript(SCHEMA_SQL)
-        self._db.commit()
+        current_version = self._db.execute("PRAGMA user_version").fetchone()[0]
+
+        if current_version == 0:
+            # Check if tables already exist (pre-migration install)
+            has_tables = self._db.execute(
+                "SELECT name FROM sqlite_master WHERE type='table' AND name='documents'"
+            ).fetchone() is not None
+
+            if not has_tables:
+                # Brand new database: create full schema
+                self._db.executescript(SCHEMA_SQL)
+                self._db.commit()
+
+            # Stamp as version 1 (baseline)
+            self._db.execute(f"PRAGMA user_version = {SCHEMA_VERSION}")
+            self._db.commit()
+            current_version = SCHEMA_VERSION
+
+        # Run any pending migrations
+        for target_version, migrate_fn in MIGRATIONS:
+            if current_version < target_version:
+                migrate_fn(self._db)
+                self._db.execute(f"PRAGMA user_version = {target_version}")
+                self._db.commit()
+                current_version = target_version
+                logger.info("Migrated schema to version %d", target_version)
 
     def close(self) -> None:
         self._db.close()
@@ -213,6 +265,21 @@ def update(self, doc_id: str, **updates: Any) -> bool:
             return True
 
         updates["updated_at"] = datetime.now(UTC).isoformat()
+
+        # Validate column names against allowlist
+        invalid_keys = set(updates.keys()) - UPDATABLE_COLUMNS
+        if invalid_keys:
+            immutable = invalid_keys & _IMMUTABLE_COLUMNS
+            if immutable:
+                raise StoreError(
+                    f"Cannot update immutable column(s): {', '.join(sorted(immutable))}",
+                    context={"columns": sorted(immutable)},
+                )
+            raise StoreError(
+                f"Unknown column(s): {', '.join(sorted(invalid_keys))}",
+                context={"columns": sorted(invalid_keys)},
+            )
+
         set_clause = ", ".join(f"{k} = ?" for k in updates)
         values = [*updates.values(), doc_id]
 
@@ -361,6 +428,21 @@ def get_embedding(self, doc_id: str) -> bytes | None:
         ).fetchone()
         return row["embedding"] if row else None
 
+    def get_all_embeddings(self, *, limit: int = 10000) -> list[dict[str, Any]]:
+        """Return all embeddings for similarity search.
+
+        Args:
+            limit: Maximum number of embeddings to return (safety cap).
+
+        Returns:
+            List of dicts with keys: doc_id, embedding (bytes), dimensions (int).
+        """
+        rows = self._db.execute(
+            "SELECT doc_id, embedding, dimensions FROM embeddings LIMIT ?",
+            (limit,),
+        ).fetchall()
+        return [dict(r) for r in rows]
+
     # -------------------------------------------------------------------------
     # Config
     # -------------------------------------------------------------------------

src/cortex/db/graph_store.py

@@ -897,17 +897,19 @@ def create_entity(
 
     def _find_entity_by_name(self, name: str) -> str | None:
         """Find entity by name (case-insensitive)."""
+        safe_name = name.replace("\\", "\\\\").replace('"', '\\"')
         query = f"""
         {SPARQL_PREFIXES}
-        SELECT ?s ?name WHERE {{
+        SELECT ?s WHERE {{
             ?s a cortex:Entity .
             ?s cortex:entityName ?name .
+            FILTER(LCASE(?name) = LCASE("{safe_name}"))
         }}
+        LIMIT 1
         """
         for row in self._store.query(query):
-            if row["name"].value.lower() == name.lower():
-                subj = str(row["s"].value)
-                return subj.split("/")[-1] if "entity/" in subj else subj
+            subj = str(row["s"].value)
+            return subj.split("/")[-1] if "entity/" in subj else subj
         return None
 
     def add_mention(self, *, obj_id: str, entity_id: str) -> None:
@@ -956,6 +958,18 @@ def list_entities(self, entity_type: str | None = None) -> list[dict[str, str]]:
             )
         return entities
 
+    def count_entities(self) -> int:
+        """Return the total number of entities without materializing the full list."""
+        query = f"""
+        {SPARQL_PREFIXES}
+        SELECT (COUNT(DISTINCT ?s) AS ?count) WHERE {{
+            ?s a cortex:Entity .
+        }}
+        """
+        for row in self._store.query(query):
+            return int(row["count"].value)
+        return 0
+
     # -------------------------------------------------------------------------
     # SPARQL Query
     # -------------------------------------------------------------------------

src/cortex/db/store.py

@@ -151,7 +151,14 @@ def update(self, obj_id: str, **updates: Any) -> bool:
             except NotFoundError:
                 pass  # Graph might not have all properties — OK
             except Exception as e:
-                logger.warning("Graph update failed for %s: %s", obj_id, e)
+                logger.warning(
+                    "Graph update failed for %s (SQLite update succeeded): %s",
+                    obj_id, e,
+                )
+                raise SyncError(
+                    f"SQLite updated but graph update failed for {obj_id}",
+                    cause=e,
+                ) from e
 
         return True
 
@@ -239,5 +246,5 @@ def status(self) -> dict[str, Any]:
             "graph_triples": self.graph.triple_count,
             "counts_by_type": content_counts,
             "graph_counts_by_type": graph_counts,
-            "entities": len(self.graph.list_entities()),
+            "entities": self.graph.count_entities(),
         }

src/cortex/pipeline/enrich.py

@@ -47,9 +47,13 @@ def run(self, obj_id: str) -> dict[str, Any]:
         }
         try:
             self.store.content.update(obj_id, **updates)
+        except Exception as e:
+            logger.warning("Content update failed during enrichment for %s: %s", obj_id, e)
+
+        try:
             self.store.graph.update_object(obj_id, tier=tier)
         except Exception as e:
-            logger.warning("Failed to update enrichment for %s: %s", obj_id, e)
+            logger.warning("Graph tier update failed during enrichment for %s: %s", obj_id, e)
 
         return {
             "status": "enriched",
@@ -101,16 +105,24 @@ def promote_to_reflex(self, obj_id: str) -> bool:
         """Explicitly promote an object to the reflex tier."""
         try:
             self.store.content.update(obj_id, tier="reflex")
-            self.store.graph.update_object(obj_id, tier="reflex")
-            return True
-        except Exception:
+        except Exception as e:
+            logger.warning("Failed to promote %s to reflex in content store: %s", obj_id, e)
             return False
+        try:
+            self.store.graph.update_object(obj_id, tier="reflex")
+        except Exception as e:
+            logger.warning("Failed to promote %s to reflex in graph store: %s", obj_id, e)
+        return True
 
     def demote_from_reflex(self, obj_id: str) -> bool:
         """Demote an object from reflex back to recall."""
         try:
             self.store.content.update(obj_id, tier="recall")
-            self.store.graph.update_object(obj_id, tier="recall")
-            return True
-        except Exception:
+        except Exception as e:
+            logger.warning("Failed to demote %s from reflex in content store: %s", obj_id, e)
             return False
+        try:
+            self.store.graph.update_object(obj_id, tier="recall")
+        except Exception as e:
+            logger.warning("Failed to demote %s from reflex in graph store: %s", obj_id, e)
+        return True

src/cortex/pipeline/link.py

@@ -5,7 +5,6 @@
 
 from __future__ import annotations
 
-import contextlib
 from typing import Any
 
 from cortex.core.constants import RELATIONSHIP_TYPES
@@ -44,8 +43,10 @@ def run(
         relationships = self._discover_relationships(obj_id)
 
         # Step 3: Update pipeline stage
-        with contextlib.suppress(Exception):
+        try:
             self.store.content.update(obj_id, pipeline_stage="linked")
+        except Exception as e:
+            logger.warning("Failed to update pipeline stage to 'linked' for %s: %s", obj_id, e)
 
         return {
             "status": "linked",

src/cortex/pipeline/normalize.py

@@ -9,7 +9,6 @@
 
 from __future__ import annotations
 
-import contextlib
 import struct
 from typing import Any
 
@@ -99,8 +98,10 @@ def run(self, obj_id: str) -> dict[str, Any]:
             graph_updates.update(
                 {k: v for k, v in classification["properties"].items() if isinstance(v, str)}
             )
-        with contextlib.suppress(Exception):
+        try:
             self.store.graph.update_object(obj_id, **graph_updates)
+        except Exception as e:
+            logger.warning("Graph update failed during normalization for %s: %s", obj_id, e)
 
         # Step 3: Generate embedding
         self._generate_embedding(obj_id, title, content)