contextwall 0.1.0__py3-none-any.whl

context_firewall/db/migrations.py

@@ -0,0 +1,408 @@
+"""Versioned SQLite migrations.
+
+Each migration is a (version, description, sql_statements) tuple.
+The runner applies only migrations whose version is higher than the
+current schema_version stored in the DB - safe to run repeatedly.
+
+Adding a migration:
+    1. Append a new entry to _MIGRATIONS with the next version number.
+    2. Never modify an existing migration entry (already applied on prod DBs).
+    3. Use ALTER TABLE ADD COLUMN (not DROP/RECREATE) for additive changes.
+"""
+
+from __future__ import annotations
+
+import logging
+
+import aiosqlite
+
+logger = logging.getLogger(__name__)
+
+# ── Migration registry ─────────────────────────────────────────────────────────
+# Each entry: (version: int, description: str, statements: list[str])
+# Statements are executed inside a transaction; if any fails the migration
+# is rolled back and startup aborts.
+
+_MIGRATIONS: list[tuple[int, str, list[str]]] = [
+    (
+        1,
+        "initial schema",
+        [
+            """
+            CREATE TABLE IF NOT EXISTS runtime_signals (
+                node_id             TEXT PRIMARY KEY,
+                invocation_count    INTEGER NOT NULL DEFAULT 0,
+                exception_count     INTEGER NOT NULL DEFAULT 0,
+                exception_rate      REAL NOT NULL DEFAULT 0.0,
+                p50_latency_ms      REAL,
+                p95_latency_ms      REAL,
+                p99_latency_ms      REAL,
+                last_observed_at    DATETIME,
+                latency_degraded    BOOLEAN NOT NULL DEFAULT FALSE,
+                exception_rate_high BOOLEAN NOT NULL DEFAULT FALSE,
+                updated_at          DATETIME NOT NULL DEFAULT CURRENT_TIMESTAMP
+            )
+            """,
+            """
+            CREATE TABLE IF NOT EXISTS service_map (
+                caller_service  TEXT NOT NULL,
+                callee_service  TEXT NOT NULL,
+                observed_count  INTEGER NOT NULL DEFAULT 1,
+                last_seen_at    DATETIME NOT NULL,
+                PRIMARY KEY (caller_service, callee_service)
+            )
+            """,
+            """
+            CREATE TABLE IF NOT EXISTS sessions (
+                session_id        TEXT PRIMARY KEY,
+                agent_id          TEXT,
+                model_version     TEXT,
+                repository_root   TEXT,
+                client_type       TEXT,
+                status            TEXT NOT NULL DEFAULT 'open',
+                started_at        DATETIME NOT NULL,
+                closed_at         DATETIME,
+                request_count     INTEGER NOT NULL DEFAULT 0,
+                total_tokens      INTEGER NOT NULL DEFAULT 0,
+                avg_outcome_score REAL
+            )
+            """,
+            """
+            CREATE TABLE IF NOT EXISTS provenance_events (
+                event_id    TEXT PRIMARY KEY,
+                event_type  TEXT NOT NULL,
+                session_id  TEXT NOT NULL,
+                request_id  TEXT NOT NULL,
+                occurred_at DATETIME NOT NULL,
+                payload     TEXT NOT NULL,
+                FOREIGN KEY (session_id) REFERENCES sessions(session_id)
+            )
+            """,
+            "CREATE INDEX IF NOT EXISTS idx_provenance_session ON provenance_events(session_id, occurred_at)",
+            "CREATE INDEX IF NOT EXISTS idx_provenance_request ON provenance_events(request_id, occurred_at)",
+            """
+            CREATE TABLE IF NOT EXISTS policy_enforcement_events (
+                id           INTEGER PRIMARY KEY AUTOINCREMENT,
+                session_id   TEXT NOT NULL,
+                request_id   TEXT NOT NULL,
+                rule_name    TEXT NOT NULL,
+                action       TEXT NOT NULL,
+                file_path    TEXT NOT NULL,
+                node_id      TEXT,
+                line_numbers TEXT,
+                reason       TEXT NOT NULL,
+                pattern_name TEXT,
+                occurred_at  DATETIME NOT NULL
+            )
+            """,
+            """
+            CREATE TABLE IF NOT EXISTS analytics_snapshots (
+                id           INTEGER PRIMARY KEY AUTOINCREMENT,
+                metric_type  TEXT NOT NULL,
+                granularity  TEXT NOT NULL,
+                key          TEXT NOT NULL,
+                payload      TEXT NOT NULL,
+                computed_at  DATETIME NOT NULL,
+                window_start DATETIME,
+                window_end   DATETIME
+            )
+            """,
+            "CREATE INDEX IF NOT EXISTS idx_analytics_type_key ON analytics_snapshots(metric_type, key, computed_at DESC)",
+            """
+            CREATE TABLE IF NOT EXISTS entropy_snapshots (
+                node_id        TEXT NOT NULL,
+                file_path      TEXT NOT NULL,
+                entropy_score  REAL NOT NULL,
+                active_signals TEXT,
+                snapshot_at    DATETIME NOT NULL,
+                PRIMARY KEY (node_id, snapshot_at)
+            )
+            """,
+            """
+            CREATE TABLE IF NOT EXISTS trust_score_snapshots (
+                node_id          TEXT NOT NULL,
+                file_path        TEXT NOT NULL,
+                trust_score      REAL NOT NULL,
+                signal_breakdown TEXT,
+                snapshot_at      DATETIME NOT NULL,
+                trigger_reason   TEXT,
+                PRIMARY KEY (node_id, snapshot_at)
+            )
+            """,
+            """
+            CREATE TABLE IF NOT EXISTS trust_signal_cache (
+                node_id          TEXT PRIMARY KEY,
+                structural_score REAL,
+                runtime_score    REAL,
+                freshness_score  REAL,
+                stability_score  REAL,
+                verification_score REAL,
+                consistency_score REAL,
+                injection_risk   REAL,
+                entropy_score    REAL,
+                cached_at        DATETIME NOT NULL
+            )
+            """,
+            """
+            CREATE TABLE IF NOT EXISTS outcome_signals (
+                id              INTEGER PRIMARY KEY AUTOINCREMENT,
+                session_id      TEXT NOT NULL,
+                request_id      TEXT NOT NULL,
+                outcome_type    TEXT NOT NULL,
+                success         BOOLEAN NOT NULL,
+                score           REAL NOT NULL,
+                node_ids        TEXT NOT NULL,
+                recorded_at     DATETIME NOT NULL
+            )
+            """,
+            """
+            CREATE TABLE IF NOT EXISTS weight_profiles (
+                profile_name         TEXT NOT NULL,
+                structural_relevance REAL NOT NULL,
+                runtime_evidence     REAL NOT NULL,
+                freshness            REAL NOT NULL,
+                stability            REAL NOT NULL,
+                verification         REAL NOT NULL,
+                consistency          REAL NOT NULL,
+                injection_risk       REAL NOT NULL,
+                entropy_contribution REAL NOT NULL,
+                updated_at           DATETIME NOT NULL,
+                PRIMARY KEY (profile_name)
+            )
+            """,
+            """
+            CREATE TABLE IF NOT EXISTS entropy_annotations (
+                node_id          TEXT PRIMARY KEY,
+                file_path        TEXT NOT NULL,
+                entropy_score    REAL NOT NULL,
+                signals          TEXT NOT NULL,
+                reasons          TEXT NOT NULL,
+                computed_at      DATETIME NOT NULL,
+                stale            BOOLEAN NOT NULL DEFAULT FALSE
+            )
+            """,
+            """
+            CREATE TABLE IF NOT EXISTS git_metadata (
+                file_path        TEXT PRIMARY KEY,
+                last_commit_at   DATETIME,
+                commit_count_30d INTEGER NOT NULL DEFAULT 0,
+                author_count     INTEGER NOT NULL DEFAULT 0,
+                indexed_at       DATETIME NOT NULL
+            )
+            """,
+            """
+            CREATE TABLE IF NOT EXISTS provenance_chain (
+                event_id    TEXT PRIMARY KEY,
+                sequence    INTEGER NOT NULL,
+                prev_hash   TEXT NOT NULL,
+                entry_hash  TEXT NOT NULL,
+                chained_at  DATETIME NOT NULL,
+                FOREIGN KEY (event_id) REFERENCES provenance_events(event_id)
+            )
+            """,
+            "CREATE UNIQUE INDEX IF NOT EXISTS idx_chain_sequence ON provenance_chain(sequence)",
+            """
+            CREATE TABLE IF NOT EXISTS compliance_bundles (
+                bundle_id    TEXT PRIMARY KEY,
+                scope_json   TEXT NOT NULL,
+                signature    TEXT NOT NULL DEFAULT '',
+                generated_at DATETIME NOT NULL
+            )
+            """,
+            """
+            CREATE TABLE IF NOT EXISTS key_store (
+                key_id       TEXT PRIMARY KEY,
+                public_key   TEXT NOT NULL,
+                algorithm    TEXT NOT NULL DEFAULT 'Ed25519',
+                created_at   DATETIME NOT NULL
+            )
+            """,
+        ],
+    ),
+    (
+        2,
+        "source trust registry",
+        [
+            """
+            CREATE TABLE IF NOT EXISTS sources (
+                id                  TEXT PRIMARY KEY,
+                source_type         TEXT NOT NULL,
+                trust_tier          TEXT NOT NULL DEFAULT 'untrusted',
+                owner               TEXT NOT NULL DEFAULT '',
+                region              TEXT NOT NULL DEFAULT '',
+                data_classification TEXT NOT NULL DEFAULT 'internal',
+                compliance_scope    TEXT NOT NULL DEFAULT '[]',
+                config_json         TEXT NOT NULL DEFAULT '{}',
+                created_at          DATETIME NOT NULL,
+                deleted_at          DATETIME
+            )
+            """,
+        ],
+    ),
+    (
+        3,
+        "transparent proxy tokens",
+        [
+            """
+            CREATE TABLE IF NOT EXISTS proxy_tokens (
+                key_id        TEXT PRIMARY KEY,
+                key_hash      TEXT NOT NULL UNIQUE,
+                project_id    TEXT NOT NULL,
+                project_name  TEXT NOT NULL,
+                provider      TEXT NOT NULL DEFAULT 'any',
+                upstream_key  TEXT NOT NULL,
+                scopes        TEXT NOT NULL DEFAULT '["proxy"]',
+                created_at    TEXT NOT NULL,
+                revoked       INTEGER NOT NULL DEFAULT 0
+            )
+            """,
+        ],
+    ),
+    (
+        4,
+        "policy enforcement index for analytics",
+        [
+            "CREATE INDEX IF NOT EXISTS idx_enforcement_rule ON policy_enforcement_events(rule_name, occurred_at DESC)",
+            "CREATE INDEX IF NOT EXISTS idx_enforcement_session ON policy_enforcement_events(session_id, occurred_at DESC)",
+        ],
+    ),
+    (
+        5,
+        "lint findings table",
+        [
+            """
+            CREATE TABLE IF NOT EXISTS lint_findings (
+                id          INTEGER PRIMARY KEY AUTOINCREMENT,
+                ran_at      TEXT    NOT NULL,
+                window_days INTEGER NOT NULL DEFAULT 30,
+                category    TEXT    NOT NULL,
+                severity    TEXT    NOT NULL,
+                subject     TEXT    NOT NULL,
+                detail      TEXT    NOT NULL DEFAULT '',
+                suggestion  TEXT    NOT NULL DEFAULT '',
+                created_at  TEXT    NOT NULL DEFAULT CURRENT_TIMESTAMP
+            )
+            """,
+            "CREATE INDEX IF NOT EXISTS idx_lint_ran_at ON lint_findings(ran_at DESC)",
+            "CREATE INDEX IF NOT EXISTS idx_lint_severity ON lint_findings(severity, category)",
+        ],
+    ),
+    (
+        6,
+        "source enforcement penalties",
+        [
+            # Track cumulative violation history per source for trust score compounding.
+            # penalty_score is a [0,1] float: 0 = clean, 1 = maximum distrust.
+            # It decays toward 0 over time and compounds on each new deny event.
+            """
+            CREATE TABLE IF NOT EXISTS source_enforcement_penalties (
+                source_id         TEXT PRIMARY KEY,
+                violation_count   INTEGER NOT NULL DEFAULT 0,
+                penalty_score     REAL NOT NULL DEFAULT 0.0,
+                last_violation_at DATETIME NOT NULL,
+                updated_at        DATETIME NOT NULL DEFAULT CURRENT_TIMESTAMP
+            )
+            """,
+            "CREATE INDEX IF NOT EXISTS idx_sep_updated ON source_enforcement_penalties(updated_at DESC)",
+            # Add source_id to enforcement events so blocks can be traced back to sources.
+            "ALTER TABLE policy_enforcement_events ADD COLUMN source_id TEXT NOT NULL DEFAULT ''",
+        ],
+    ),
+    (
+        7,
+        "sources: rename source_type column to type",
+        [
+            # Migration 2 created the sources table with column 'source_type', but all
+            # registry code uses 'type'. SQLite has no RENAME COLUMN before 3.25, so
+            # we recreate the table. COALESCE handles DBs where _migrate() already added
+            # a 'type' column alongside the original 'source_type'.
+            """
+            CREATE TABLE IF NOT EXISTS sources_v7 (
+                id                  TEXT PRIMARY KEY,
+                type                TEXT NOT NULL DEFAULT 'unknown',
+                trust_tier          TEXT NOT NULL DEFAULT 'untrusted',
+                owner               TEXT NOT NULL DEFAULT '',
+                region              TEXT NOT NULL DEFAULT '',
+                data_classification TEXT NOT NULL DEFAULT '',
+                created_at          DATETIME NOT NULL DEFAULT CURRENT_TIMESTAMP,
+                updated_at          DATETIME NOT NULL DEFAULT CURRENT_TIMESTAMP,
+                config              TEXT NOT NULL DEFAULT '{}',
+                deleted_at          DATETIME
+            )
+            """,
+            """
+            INSERT OR IGNORE INTO sources_v7
+                (id, type, trust_tier, owner, region, data_classification,
+                 created_at, updated_at, config, deleted_at)
+            SELECT
+                id,
+                COALESCE(source_type, 'unknown'),
+                COALESCE(trust_tier, 'untrusted'),
+                COALESCE(owner, ''),
+                COALESCE(region, ''),
+                COALESCE(data_classification, ''),
+                COALESCE(created_at, CURRENT_TIMESTAMP),
+                CURRENT_TIMESTAMP,
+                COALESCE(config_json, '{}'),
+                deleted_at
+            FROM sources
+            """,
+            "DROP TABLE sources",
+            "ALTER TABLE sources_v7 RENAME TO sources",
+            "CREATE INDEX IF NOT EXISTS idx_sources_tier ON sources(trust_tier) WHERE deleted_at IS NULL",
+        ],
+    ),
+]
+
+
+# ── Runner ─────────────────────────────────────────────────────────────────────
+
+async def run_migrations(db_path: str) -> None:
+    async with aiosqlite.connect(db_path) as db:
+        db.row_factory = aiosqlite.Row
+        await db.execute("PRAGMA journal_mode=WAL")
+        await db.execute("PRAGMA foreign_keys=ON")
+
+        # Bootstrap the version tracking table
+        await db.execute("""
+            CREATE TABLE IF NOT EXISTS schema_version (
+                version      INTEGER NOT NULL,
+                description  TEXT NOT NULL,
+                applied_at   DATETIME NOT NULL DEFAULT CURRENT_TIMESTAMP
+            )
+        """)
+        await db.commit()
+
+        async with db.execute("SELECT MAX(version) AS v FROM schema_version") as cur:
+            row = await cur.fetchone()
+        current = row["v"] if row["v"] is not None else 0
+
+        pending = [(v, desc, stmts) for v, desc, stmts in _MIGRATIONS if v > current]
+        if not pending:
+            logger.debug("schema up to date at version %d", current)
+            return
+
+        for version, description, statements in pending:
+            logger.info("applying migration %d: %s", version, description)
+            try:
+                for stmt in statements:
+                    await db.execute(stmt)
+                await db.execute(
+                    "INSERT INTO schema_version (version, description) VALUES (?, ?)",
+                    (version, description),
+                )
+                await db.commit()
+                logger.info("migration %d applied", version)
+            except Exception as e:
+                await db.rollback()
+                logger.error(
+                    "migration %d failed - rolling back: %s", version, e
+                )
+                raise RuntimeError(f"Migration {version} ({description}) failed: {e}") from e
+
+        logger.info(
+            "migrations complete: %d → %d (%d applied)",
+            current,
+            pending[-1][0],
+            len(pending),
+        )

context_firewall/entropy/__init__.py

@@ -0,0 +1,5 @@
+"""Context Entropy Engine - offline entropy signal computation."""
+
+from context_firewall.entropy.engine import ContextEntropyEngine
+
+__all__ = ["ContextEntropyEngine"]

context_firewall/entropy/engine.py

@@ -0,0 +1,271 @@
+"""Context Entropy Engine - computes entropy annotations offline."""
+
+from __future__ import annotations
+
+import asyncio
+import json
+import logging
+import re
+from datetime import datetime, timezone
+from pathlib import Path
+
+import aiosqlite
+
+from context_firewall.config import Config
+from context_firewall.models import EntropyAnnotation, SubsystemHealth
+
+logger = logging.getLogger(__name__)
+
+# Heuristics: these patterns signal expected divergence, not entropy
+_SKIP_PATTERNS = [
+    re.compile(r"//\s*cre:skip"),
+    re.compile(r"#\s*cre:skip"),
+    re.compile(r"(?i)legacy"),
+    re.compile(r"(?i)feature.?flag"),
+    re.compile(r"(?i)retry"),
+]
+
+_NAMING_INCONSISTENCY_PAIRS = [
+    (re.compile(r"\bget\w+\b"), re.compile(r"\bfetch\w+\b")),
+    (re.compile(r"\bcreate\w+\b"), re.compile(r"\bnew\w+\b")),
+    (re.compile(r"\bdelete\w+\b"), re.compile(r"\bremove\w+\b")),
+]
+
+
+def _has_skip_annotation(content: str) -> bool:
+    return any(p.search(content) for p in _SKIP_PATTERNS)
+
+
+def _compute_naming_inconsistency(content: str) -> float:
+    """Detect mixed naming conventions (get/fetch, create/new, delete/remove)."""
+    score = 0.0
+    for pattern_a, pattern_b in _NAMING_INCONSISTENCY_PAIRS:
+        has_a = bool(pattern_a.search(content))
+        has_b = bool(pattern_b.search(content))
+        if has_a and has_b:
+            score += 0.33
+    return min(1.0, score)
+
+
+def _compute_dead_code_references(content: str) -> float:
+    """Proxy: deprecated/todo/fixme markers as dead code signal."""
+    markers = re.findall(r"(?i)(deprecated|todo|fixme|hack|xxx|dead.?code)", content)
+    return min(1.0, len(markers) * 0.15)
+
+
+def _compute_contradictory_documentation(content: str) -> float:
+    """Structural contradiction: docstring describes opposite of what code does."""
+    doc_lines = re.findall(r'""".*?"""', content, re.DOTALL)
+    negations = 0
+    for doc in doc_lines:
+        negations += len(re.findall(r"\b(not|never|no longer|deprecated|do not|don\'t)\b", doc, re.I))
+    return min(1.0, negations * 0.2)
+
+
+def _compute_semantic_duplication(content_a: str, content_b: str) -> float:
+    """Jaccard similarity on significant token sets between two files."""
+    tokens_a = set(t for t in re.findall(r"[a-zA-Z_]\w{3,}", content_a.lower()) if len(t) > 4)
+    tokens_b = set(t for t in re.findall(r"[a-zA-Z_]\w{3,}", content_b.lower()) if len(t) > 4)
+    if not tokens_a or not tokens_b:
+        return 0.0
+    intersection = tokens_a & tokens_b
+    union = tokens_a | tokens_b
+    return len(intersection) / len(union)
+
+
+def _compute_divergent_execution_paths(content: str) -> float:
+    """Estimate branching complexity from structural patterns."""
+    lines = content.split("\n")
+    total = max(1, len(lines))
+    # Count branching constructs normalized to file length
+    branches = 0
+    for line in lines:
+        stripped = line.lstrip()
+        if re.match(r"(if |elif |else:|except |except:|finally:|case )", stripped):
+            branches += 1
+        elif re.match(r"(for |while )", stripped):
+            branches += 0.5
+    # Also penalize high cyclomatic density: > 1 branch per 8 lines is high
+    density = branches / (total / 8)
+    return min(1.0, density * 0.4)
+
+
+def _compute_runtime_inconsistency(content: str) -> float:
+    """Detect non-deterministic sources: random, time, env vars, network."""
+    patterns = [
+        r"\brandom\b", r"\brandint\b", r"\brandrange\b", r"\buuid\b",
+        r"\bdatetime\.now\b", r"\btime\.time\b", r"\btime\.sleep\b",
+        r"\bos\.environ\b", r"\bgetenv\b",
+        r"\bsocket\.", r"\brequests\.", r"\bhttpx\.", r"\baiohttp\.",
+        r"\bopen\(.*[rwa]", r"\bsubprocess\.",
+    ]
+    hits = sum(1 for p in patterns if re.search(p, content, re.I))
+    return min(1.0, hits * 0.12)
+
+
+def _aggregate_entropy(signals: dict[str, float]) -> float:
+    weights = {
+        "semantic_duplication": 0.25,
+        "divergent_execution_paths": 0.20,
+        "contradictory_documentation": 0.20,
+        "dead_code_references": 0.15,
+        "naming_inconsistency": 0.10,
+        "runtime_inconsistency": 0.10,
+    }
+    total = sum(weights.get(k, 0.0) * v for k, v in signals.items())
+    return max(0.0, min(1.0, total))
+
+
+class ContextEntropyEngine:
+    name = "context_entropy_engine"
+    critical = False
+
+    def __init__(self) -> None:
+        self._config: Config | None = None
+        self._db: aiosqlite.Connection | None = None
+
+    async def init(self, config: Config) -> None:
+        self._config = config
+        from context_firewall.db.connection import get_db
+        self._db = await get_db()
+        logger.info("ContextEntropyEngine initialized")
+
+    def health_check(self) -> SubsystemHealth:
+        return SubsystemHealth(name=self.name, healthy=True)
+
+    async def shutdown(self) -> None:
+        self._db = None
+
+    async def get_entropy(self, node_id: str) -> float:
+        """Hot-path: O(1) lookup from pre-computed annotations."""
+        if self._db is None:
+            return self._config.entropy.default_score if self._config else 0.30
+        try:
+            async with self._db.execute(
+                "SELECT entropy_score, stale FROM entropy_annotations WHERE node_id = ?",
+                (node_id,),
+            ) as cursor:
+                row = await cursor.fetchone()
+            if row is None:
+                return self._config.entropy.default_score if self._config else 0.30
+            score = float(row["entropy_score"])
+            if row["stale"]:
+                score = min(1.0, score + 0.15)
+            return score
+        except Exception:
+            logger.warning("entropy score lookup failed for node %s", node_id, exc_info=True)
+            return 0.30
+
+    async def run_analysis(self, repository_root: str) -> int:
+        """Offline: compute entropy for all files in repository_root."""
+        root = Path(repository_root)
+        annotated = 0
+        exts = ("*.py", "*.ts", "*.go", "*.tsx", "*.js")
+        files = []
+        for ext in exts:
+            files.extend(root.rglob(ext))
+
+        # Load contents once so we can do cross-file duplication comparisons
+        contents: list[tuple[str, str]] = []
+        for file_path in files:
+            try:
+                content = file_path.read_text(errors="ignore")
+                rel = str(file_path.relative_to(root))
+                contents.append((rel, content))
+            except Exception as e:
+                logger.debug("could not read %s: %s", file_path, e)
+
+        for i, (rel_path, content) in enumerate(contents):
+            try:
+                # Use adjacent file for duplication comparison (avoids O(N^2) over all files)
+                sibling_content = contents[i - 1][1] if i > 0 else ""
+                annotation = await self._analyze_file(rel_path, content, sibling_content)
+                await self._persist(annotation)
+                annotated += 1
+            except Exception as e:
+                logger.debug("entropy analysis skipped", extra={"file": rel_path, "error": str(e)})
+        logger.info("entropy analysis complete", extra={"annotated": annotated})
+        return annotated
+
+    async def _analyze_file(
+        self, file_path: str, content: str, sibling_content: str = ""
+    ) -> EntropyAnnotation:
+        if _has_skip_annotation(content):
+            signals = {k: 0.0 for k in [
+                "semantic_duplication", "divergent_execution_paths",
+                "contradictory_documentation", "dead_code_references",
+                "naming_inconsistency", "runtime_inconsistency",
+            ]}
+            return EntropyAnnotation(
+                node_id=file_path,
+                file_path=file_path,
+                entropy_score=0.0,
+                signals=signals,
+                reasons=["cre:skip annotation present"],
+                computed_at=datetime.now(timezone.utc),
+            )
+
+        signals: dict[str, float] = {}
+        reasons: list[str] = []
+
+        signals["naming_inconsistency"] = _compute_naming_inconsistency(content)
+        if signals["naming_inconsistency"] > 0.3:
+            reasons.append("mixed naming conventions detected")
+
+        signals["dead_code_references"] = _compute_dead_code_references(content)
+        if signals["dead_code_references"] > 0.3:
+            reasons.append("deprecated/todo markers found")
+
+        signals["contradictory_documentation"] = _compute_contradictory_documentation(content)
+        if signals["contradictory_documentation"] > 0.3:
+            reasons.append("potential doc/code contradiction")
+
+        signals["semantic_duplication"] = (
+            _compute_semantic_duplication(content, sibling_content) if sibling_content else 0.0
+        )
+        if signals["semantic_duplication"] > 0.55:
+            reasons.append("high token overlap with adjacent file")
+
+        signals["divergent_execution_paths"] = _compute_divergent_execution_paths(content)
+        if signals["divergent_execution_paths"] > 0.5:
+            reasons.append("high branching complexity")
+
+        signals["runtime_inconsistency"] = _compute_runtime_inconsistency(content)
+        if signals["runtime_inconsistency"] > 0.4:
+            reasons.append("non-deterministic runtime sources detected")
+
+        entropy_score = _aggregate_entropy(signals)
+        return EntropyAnnotation(
+            node_id=file_path,
+            file_path=file_path,
+            entropy_score=entropy_score,
+            signals=signals,
+            reasons=reasons,
+            computed_at=datetime.now(timezone.utc),
+        )
+
+    async def _persist(self, annotation: EntropyAnnotation) -> None:
+        if self._db is None:
+            return
+        await self._db.execute(
+            """
+            INSERT INTO entropy_annotations
+                (node_id, file_path, entropy_score, signals, reasons, computed_at, stale)
+            VALUES (?, ?, ?, ?, ?, ?, FALSE)
+            ON CONFLICT(node_id) DO UPDATE SET
+                entropy_score = excluded.entropy_score,
+                signals = excluded.signals,
+                reasons = excluded.reasons,
+                computed_at = excluded.computed_at,
+                stale = FALSE
+            """,
+            (
+                annotation.node_id,
+                annotation.file_path,
+                annotation.entropy_score,
+                json.dumps(annotation.signals),
+                json.dumps(annotation.reasons),
+                annotation.computed_at.isoformat(),
+            ),
+        )
+        await self._db.commit()

context_firewall/graph/__init__.py

@@ -0,0 +1,5 @@
+"""Repository Graph Engine - KuzuDB-backed graph traversal."""
+
+from context_firewall.graph.engine import RepositoryGraphEngine
+
+__all__ = ["RepositoryGraphEngine"]