superlocalmemory 3.4.18 → 3.4.21

package/src/superlocalmemory/core/shadow_router.py

@@ -0,0 +1,319 @@
+# Copyright (c) 2026 Varun Pratap Bhardwaj / Qualixar
+# Licensed under AGPL-3.0-or-later - see LICENSE file
+# Part of SuperLocalMemory v3.4.21 — Stage 8 SB-1 / Track A.3 (LLD-10)
+
+"""Daemon-resident recall-time A/B router for LLD-10 shadow + rollback.
+
+This module is the single seam that wires ``ShadowTest`` (pre-promotion)
+and ``ModelRollback`` (post-promotion) into the live recall path. Before
+this module existed (pre-v3.4.21 Stage 8 SB-1) both classes were
+defined + unit-tested but had zero production callers in ``src/``.
+
+Design constraints:
+
+  * Process-local state only — one ``ShadowRouter`` instance per
+    ``(memory_db, learning_db, profile_id)`` tuple, held by the
+    daemon's in-process singleton cache.
+  * Deterministic A/B routing — ``route_query(qid)`` uses
+    ``sha256(install_token + qid)`` so an attacker who controls
+    ``qid`` still cannot bias the split without reading the install
+    token on disk (closes skeptic H-02 + H-03).
+  * Promotion and rollback are DELEGATED to the canonical helpers in
+    ``learning/consolidation_worker`` and ``learning/model_rollback``.
+    The router never writes to ``learning_model_state`` directly.
+  * Fail-soft: any exception during recall-time ingestion is logged
+    and swallowed — we must not break the user's recall path.
+
+References:
+  - LLD-00 §8    — two-phase shadow + auto-rollback.
+  - LLD-10 §4.1  — deterministic A/B routing.
+  - LLD-10 §5    — atomic BEGIN IMMEDIATE promotion + rollback.
+  - Stage 8 SB-1 — architect S8-ARC-C1, skeptic C-01/C-02/H-07.
+"""
+
+from __future__ import annotations
+
+import hashlib
+import logging
+import threading
+from typing import Final
+
+from superlocalmemory.core.security_primitives import ensure_install_token
+from superlocalmemory.learning.model_rollback import ModelRollback
+from superlocalmemory.learning.shadow_test import ShadowTest
+
+logger = logging.getLogger(__name__)
+
+
+# ---------------------------------------------------------------------------
+# Arm vocabulary — externalised so hooks can grep-check.
+# ---------------------------------------------------------------------------
+
+ARM_BASELINE: Final[str] = "baseline"
+ARM_CANDIDATE: Final[str] = "candidate"
+
+
+class ShadowRouter:
+    """Per-profile A/B router + post-promotion watcher.
+
+    Not thread-safe for write state (`_shadow`, `_rollback`) — the daemon
+    calls ``on_recall_settled`` from a single recall-settled worker queue.
+    Reads (``route_query``) are safe under concurrency.
+    """
+
+    def __init__(
+        self,
+        *,
+        memory_db: str,
+        learning_db: str,
+        profile_id: str,
+    ) -> None:
+        self._memory_db = str(memory_db)
+        self._learning_db = str(learning_db)
+        self._profile_id = str(profile_id)
+        # Shadow pre-promotion accumulator (created lazily when a
+        # candidate is persisted).
+        self._shadow: ShadowTest | None = None
+        self._candidate_id: int | None = None
+        # S9-SKEP-11: pin the routing token at router creation.
+        # ``install_token`` rotation is a documented user action (SEC-M07
+        # ``slm escape-hatch rotate-token``) but must not flip the arm
+        # assignment of every in-flight query_id — that would silently
+        # mix baseline and candidate observations for the same qid and
+        # break the paired-t assumption. We snapshot the token once at
+        # init; subsequent rotations are picked up only when a new
+        # router is created (i.e. at daemon restart / candidate rotate).
+        try:
+            self._routing_token = ensure_install_token()
+        except Exception:  # pragma: no cover — defensive
+            self._routing_token = ""
+        # Rollback post-promotion watcher (created when arm_post_promotion
+        # is called after a promote).
+        self._rollback: ModelRollback | None = None
+        # S9-W4 H-ARC-01: re-attach an existing candidate across daemon
+        # restart. The prior implementation lost the candidate_id on
+        # process exit — a 6-hour shadow test that had persisted a
+        # candidate an hour in would restart the observation window
+        # from zero on the next boot, extending the test indefinitely.
+        # Observations themselves do NOT survive restart (they live
+        # only in ``ShadowTest._active/_candidate`` lists and would
+        # require a new schema to persist durably); re-attaching the
+        # candidate_id is the minimum that keeps the A/B loop from
+        # silently stalling.
+        self._reattach_existing_candidate()
+
+    def _reattach_existing_candidate(self) -> None:
+        """H-ARC-01: look up any ``is_candidate=1`` row for this profile
+        and restore ``self._candidate_id`` + a fresh ``ShadowTest``.
+
+        Fail-soft — on any DB error we leave the router empty and the
+        normal lazy-init path takes over as candidates land.
+        """
+        try:
+            import sqlite3 as _sq
+            conn = _sq.connect(self._learning_db, timeout=2.0)
+            try:
+                row = conn.execute(
+                    "SELECT id FROM learning_model_state "
+                    "WHERE profile_id = ? AND is_candidate = 1 "
+                    "LIMIT 1",
+                    (self._profile_id,),
+                ).fetchone()
+            finally:
+                conn.close()
+        except Exception:
+            return  # learning.db or table missing — normal cold start.
+        if row and row[0] is not None:
+            cid = int(row[0])
+            self._candidate_id = cid
+            # Pass learning_db so ShadowTest reloads persisted paired
+            # observations from ``shadow_observations`` (M012).
+            self._shadow = ShadowTest(
+                profile_id=self._profile_id,
+                candidate_model_id=str(cid),
+                learning_db=self._learning_db,
+            )
+
+    # ------------------------------------------------------------------
+    # Routing
+    # ------------------------------------------------------------------
+
+    def route_query(self, query_id: str) -> str:
+        """Return the arm for ``query_id``: ``'baseline'`` or ``'candidate'``.
+
+        Deterministic per ``(install_token, query_id)`` — survives
+        daemon restart. Install-token dependence closes the
+        attacker-picks-query-id bias vector (skeptic H-02).
+
+        S9-SKEP-11: uses ``self._routing_token`` (pinned at router
+        init) instead of a fresh ``ensure_install_token()`` per call,
+        so mid-test token rotation does not silently flip the arm of
+        every subsequent qid and mix the paired-t arms.
+        """
+        digest = hashlib.sha256(
+            (self._routing_token + str(query_id)).encode("utf-8"),
+        ).hexdigest()[:8]
+        return ARM_CANDIDATE if int(digest, 16) % 2 == 1 else ARM_BASELINE
+
+    # ------------------------------------------------------------------
+    # Pre-promotion accumulator
+    # ------------------------------------------------------------------
+
+    def attach_candidate(self, candidate_id: int) -> None:
+        """Called after ``_persist_candidate`` writes a fresh candidate row.
+        Creates a new ``ShadowTest`` to collect paired recall results.
+        """
+        self._candidate_id = int(candidate_id)
+        # Pass learning_db so new paired observations persist to
+        # ``shadow_observations`` (M012) for restart durability.
+        self._shadow = ShadowTest(
+            profile_id=self._profile_id,
+            candidate_model_id=str(candidate_id),
+            learning_db=self._learning_db,
+        )
+
+    # ------------------------------------------------------------------
+    # Post-promotion watcher
+    # ------------------------------------------------------------------
+
+    def arm_post_promotion_watch(self, *, baseline_ndcg: float) -> None:
+        """Install a fresh ``ModelRollback`` observer for the 200-recall
+        post-promotion watch window."""
+        self._rollback = ModelRollback(
+            learning_db_path=self._learning_db,
+            profile_id=self._profile_id,
+            baseline_ndcg=float(baseline_ndcg),
+        )
+
+    # ------------------------------------------------------------------
+    # Recall-settled ingestion
+    # ------------------------------------------------------------------
+
+    def on_recall_settled(
+        self,
+        *,
+        query_id: str,
+        arm: str,
+        ndcg_at_10: float,
+    ) -> None:
+        """Feed one settled recall into whichever phase is active.
+
+        Precedence:
+          1. If a ShadowTest is active → record paired observation; on
+             ``decide() == 'promote'`` fire the atomic promotion.
+          2. If a ModelRollback watch is active → record observation;
+             on ``should_rollback() is True`` fire execute_rollback.
+
+        Both phases may run for the same profile briefly if a promote
+        fires mid-batch; that is intentional — the first watch window
+        starts immediately on promotion.
+        """
+        try:
+            if self._shadow is not None and self._candidate_id is not None:
+                # ShadowTest expects arm='active'|'candidate'. Our router
+                # uses 'baseline' as the externally-visible arm name.
+                st_arm = "active" if arm == ARM_BASELINE else "candidate"
+                self._shadow.record_recall_pair(
+                    query_id=str(query_id), arm=st_arm,
+                    ndcg_at_10=float(ndcg_at_10),
+                )
+                decision, _stats = self._shadow.decide()
+                if decision == "promote":
+                    self._fire_promotion()
+                elif decision == "reject":
+                    # Release the candidate reservation — a future
+                    # _run_shadow_cycle may insert a new candidate.
+                    self._shadow = None
+                    self._candidate_id = None
+
+            if self._rollback is not None:
+                self._rollback.record_post_promotion(
+                    query_id=str(query_id), ndcg_at_10=float(ndcg_at_10),
+                )
+                if self._rollback.should_rollback():
+                    self._fire_rollback()
+        except Exception as exc:  # pragma: no cover — defensive
+            logger.debug("shadow_router on_recall_settled error: %s", exc)
+
+    # ------------------------------------------------------------------
+    # Internal: promotion + rollback triggers
+    # ------------------------------------------------------------------
+
+    def _fire_promotion(self) -> None:
+        """Call the canonical ``_promote_candidate`` helper and reset
+        the shadow state so a new A/B cycle can start next retrain."""
+        if self._candidate_id is None:
+            return
+        try:
+            from superlocalmemory.learning.consolidation_worker import (
+                _promote_candidate,
+            )
+            _promote_candidate(
+                self._learning_db,
+                profile_id=self._profile_id,
+                candidate_id=int(self._candidate_id),
+            )
+        except Exception as exc:  # pragma: no cover — defensive
+            logger.warning("shadow_router promotion failed: %s", exc)
+        finally:
+            self._shadow = None
+            self._candidate_id = None
+
+    def _fire_rollback(self) -> None:
+        """Call ``ModelRollback.execute_rollback`` and clear the watcher."""
+        try:
+            if self._rollback is not None:
+                self._rollback.execute_rollback(
+                    reason="watch_window_regression",
+                )
+        except Exception as exc:  # pragma: no cover — defensive
+            logger.warning("shadow_router rollback failed: %s", exc)
+        finally:
+            self._rollback = None
+
+
+# ---------------------------------------------------------------------------
+# Process-local singleton cache — one ShadowRouter per (learning_db, profile).
+# Thread-safe; keyed by a stable tuple so repeated factory calls reuse state.
+# ---------------------------------------------------------------------------
+
+
+_CACHE: dict[tuple[str, str, str], ShadowRouter] = {}
+_CACHE_LOCK = threading.Lock()
+
+
+def get_shadow_router(
+    *,
+    memory_db: str,
+    learning_db: str,
+    profile_id: str,
+) -> ShadowRouter:
+    """Factory — returns the process-local ``ShadowRouter`` for
+    ``(memory_db, learning_db, profile_id)``, creating one on first call.
+    """
+    key = (str(memory_db), str(learning_db), str(profile_id))
+    with _CACHE_LOCK:
+        router = _CACHE.get(key)
+        if router is None:
+            router = ShadowRouter(
+                memory_db=memory_db,
+                learning_db=learning_db,
+                profile_id=profile_id,
+            )
+            _CACHE[key] = router
+        return router
+
+
+def reset_for_testing() -> None:
+    """Clear the singleton cache — tests only."""
+    with _CACHE_LOCK:
+        _CACHE.clear()
+
+
+__all__ = (
+    "ARM_BASELINE",
+    "ARM_CANDIDATE",
+    "ShadowRouter",
+    "get_shadow_router",
+    "reset_for_testing",
+)

package/src/superlocalmemory/core/slm_disabled.py

@@ -0,0 +1,87 @@
+# Copyright (c) 2026 Varun Pratap Bhardwaj / Qualixar
+# Licensed under AGPL-3.0-or-later - see LICENSE file
+# Part of SuperLocalMemory v3.4.21 — Stage 8 SB-5
+
+"""Global kill-switch for SLM.
+
+Two mechanisms, either disables the entire system cheaply:
+
+1. File-marker: ``~/.superlocalmemory/.disabled`` — persistent across
+   reboots, survives daemon restarts, written by ``slm disable``.
+2. Environment variable: ``SLM_DISABLE=1`` — per-process, useful for
+   CI, sandboxes, or "just for this shell" overrides.
+
+Every hot-path entry point (hooks, MCP tools, recall pipeline, daemon
+lifespan) calls :func:`is_disabled` first. Returns ``True`` ⇒ exit
+quietly, no side effects.
+
+Backward-compat: unset env + missing marker ⇒ ``False`` ⇒ normal
+behaviour. Zero impact on the 18k live users who never touch it.
+"""
+
+from __future__ import annotations
+
+import os
+from pathlib import Path
+
+
+_MARKER_NAME = ".disabled"
+_ENV_NAME = "SLM_DISABLE"
+
+
+def _slm_home() -> Path:
+    """Return the SLM state directory. Override via ``SLM_HOME`` env."""
+    override = os.environ.get("SLM_HOME")
+    if override:
+        return Path(override)
+    return Path.home() / ".superlocalmemory"
+
+
+def marker_path() -> Path:
+    """Where the persistent ``.disabled`` marker lives."""
+    return _slm_home() / _MARKER_NAME
+
+
+def is_disabled() -> bool:
+    """Return True iff SLM should no-op everything.
+
+    Precedence: env var first (cheapest check), then file marker. Any
+    non-empty, non-"0", non-"false" value in the env counts as disabled.
+    """
+    env = os.environ.get(_ENV_NAME, "").strip().lower()
+    if env and env not in ("0", "false", "no", "off"):
+        return True
+    try:
+        return marker_path().exists()
+    except OSError:  # pragma: no cover — defensive against FS errors
+        return False
+
+
+def write_marker(reason: str = "") -> Path:
+    """Create the disabled marker. Returns the path."""
+    home = _slm_home()
+    home.mkdir(parents=True, exist_ok=True)
+    path = home / _MARKER_NAME
+    payload = "disabled"
+    if reason:
+        payload = f"disabled: {reason}\n"
+    path.write_text(payload, encoding="utf-8")
+    return path
+
+
+def remove_marker() -> bool:
+    """Remove the disabled marker. Returns True if removed, False if absent."""
+    path = marker_path()
+    try:
+        path.unlink()
+        return True
+    except FileNotFoundError:
+        return False
+
+
+__all__ = (
+    "is_disabled",
+    "write_marker",
+    "remove_marker",
+    "marker_path",
+)

package/src/superlocalmemory/core/slmignore.py

@@ -0,0 +1,125 @@
+# Copyright (c) 2026 Varun Pratap Bhardwaj / Qualixar
+# Licensed under AGPL-3.0-or-later - see LICENSE file
+# Part of SuperLocalMemory v3.4.21 — Stage 8 SB-5
+
+"""Path-level opt-out via ``.slmignore``.
+
+A repository-scoped escape hatch: drop a ``.slmignore`` at any
+ancestor of a workspace and SLM will skip hooks / recall / remember
+for any path inside that ancestor. Roughly the shape of ``.gitignore``
+but with simpler matching — one path pattern per line, ``#`` comments,
+whitespace stripped.
+
+Matching rules (intentionally minimal):
+
+- Lines starting with ``#`` or empty ⇒ ignored.
+- A line like ``node_modules`` matches any path segment named
+  ``node_modules`` anywhere in the resolved absolute path.
+- A line starting with ``/`` is an absolute-prefix match
+  (``/Users/me/secret`` matches everything under that dir).
+- Glob chars ``*`` / ``?`` are treated literally — keep it boring,
+  avoid re-implementing ``.gitignore``'s subtleties.
+
+Cache: the parsed ignore list is memoised per ignore-file path + mtime.
+Look-up cost at the hook hot path is O(depth × patterns) and
+patterns ≤ 50 in practice.
+"""
+
+from __future__ import annotations
+
+import os
+from pathlib import Path
+
+_FILENAME = ".slmignore"
+_CACHE: dict[tuple[str, float], tuple[str, ...]] = {}
+_CACHE_CAP = 64
+
+
+def _load_patterns(ignore_path: Path) -> tuple[str, ...]:
+    """Parse one ``.slmignore`` file, memoised by path + mtime."""
+    try:
+        stat = ignore_path.stat()
+    except OSError:
+        return ()
+    key = (str(ignore_path), stat.st_mtime)
+    cached = _CACHE.get(key)
+    if cached is not None:
+        return cached
+    try:
+        raw = ignore_path.read_text(encoding="utf-8", errors="ignore")
+    except OSError:
+        return ()
+    patterns: list[str] = []
+    for line in raw.splitlines():
+        stripped = line.strip()
+        if not stripped or stripped.startswith("#"):
+            continue
+        patterns.append(stripped)
+    result = tuple(patterns)
+    if len(_CACHE) >= _CACHE_CAP:
+        _CACHE.clear()
+    _CACHE[key] = result
+    return result
+
+
+def _iter_ancestor_ignores(target: Path) -> list[tuple[Path, tuple[str, ...]]]:
+    """Walk from ``target`` up to the filesystem root collecting ignore files."""
+    hits: list[tuple[Path, tuple[str, ...]]] = []
+    seen_dirs: set[Path] = set()
+    probe = target if target.is_dir() else target.parent
+    while probe not in seen_dirs:
+        seen_dirs.add(probe)
+        candidate = probe / _FILENAME
+        if candidate.is_file():
+            patterns = _load_patterns(candidate)
+            if patterns:
+                hits.append((candidate.parent, patterns))
+        if probe.parent == probe:
+            break
+        probe = probe.parent
+    return hits
+
+
+def path_is_ignored(target: str | Path) -> bool:
+    """Return True iff any ancestor ``.slmignore`` ignores the given path.
+
+    Absolute paths are resolved (symlinks preserved — we match on name,
+    not realpath, so a symlink into an ignored dir still matches).
+    Non-existent targets are allowed; we walk the theoretical ancestry.
+    """
+    p = Path(target)
+    try:
+        abs_path = p.resolve(strict=False)
+    except OSError:
+        abs_path = p
+    segments = set(abs_path.parts)
+    for ignore_dir, patterns in _iter_ancestor_ignores(abs_path):
+        for pat in patterns:
+            if pat.startswith("/"):
+                # Absolute prefix: the ignore file's directory provides the
+                # anchor for relative-looking absolute patterns.
+                candidate = Path(pat)
+                try:
+                    abs_path.relative_to(candidate)
+                    return True
+                except ValueError:
+                    continue
+            else:
+                # Match any path segment.
+                if pat in segments:
+                    return True
+                # Also honour a per-ignore-dir relative path.
+                rel = abs_path.relative_to(ignore_dir) if (
+                    ignore_dir in abs_path.parents or ignore_dir == abs_path
+                ) else None
+                if rel is not None and pat in set(rel.parts):
+                    return True
+    return False
+
+
+def clear_cache() -> None:
+    """Test-only helper: drop the memoised pattern cache."""
+    _CACHE.clear()
+
+
+__all__ = ("path_is_ignored", "clear_cache")

package/src/superlocalmemory/core/topic_signature.py

@@ -0,0 +1,143 @@
+# Copyright (c) 2026 Varun Pratap Bhardwaj / Qualixar
+# Licensed under AGPL-3.0-or-later - see LICENSE file
+# Part of SuperLocalMemory v3.4.21 — LLD-01 §4.2
+
+"""Topic signature — deterministic, Unicode-safe, ReDoS-resistant 16-char hex.
+
+LLD reference: `.backup/active-brain/lld/LLD-01-context-cache-and-hot-path-hooks.md`
+Section 4.2.
+
+Hot-path contract:
+  - stdlib-only imports (no third-party packages).
+  - Same (NFC-normalized, lowercased) input → same output across Python
+    versions, OSes, and locales. Enforced via CI matrix.
+  - Patterns are O(n) — no catastrophic backtracking regardless of input.
+  - Input is truncated to ``MAX_SIG_INPUT_CHARS`` BEFORE any regex to
+    guarantee a hard upper bound on compute time.
+  - Budget: <5 ms p95 at 2000 chars, <8 ms at 8000 (see tests).
+
+No ``@lru_cache`` anywhere — per LLD-01 SEC-01-01 / PERF-01-04, caching on
+raw prompts would leak secrets in memory and is useless across fresh hook
+processes anyway.
+"""
+
+from __future__ import annotations
+
+import hashlib
+import re
+import unicodedata
+
+# --------------------------------------------------------------------------
+# Non-backtracking patterns. Each one is linear in input length.
+# --------------------------------------------------------------------------
+
+# CamelCase / PascalCase identifiers (>= 2 upper-case humps).
+_CAMEL_PASCAL = re.compile(r"\b[A-Z][a-zA-Z0-9]+[A-Z][a-zA-Z0-9]*\b")
+# URLs — capture up to whitespace / angle brackets. Linear in input.
+_URL = re.compile(r"https?://[^\s<>]+")
+# Paths — absolute POSIX paths. Linear; each segment is a simple char class.
+_PATH = re.compile(r"/[^\s/<>]+(?:/[^\s/<>]+)*(?:\.[A-Za-z0-9]+)?")
+# Quoted strings (capped at 200 chars to preserve linear time bound).
+_QUOTED_DOUBLE = re.compile(r'"([^"]{1,200})"')
+_QUOTED_SINGLE = re.compile(r"'([^']{1,200})'")
+# Word tokens for content-word extraction. Length >= 3 below filters shorter.
+_WORD = re.compile(r"[A-Za-z0-9][A-Za-z0-9'\-]{2,}")
+
+# ~120 common English stopwords. Kept inline so the module is stdlib-only.
+_STOPWORDS: frozenset[str] = frozenset({
+    "a", "about", "above", "after", "again", "against", "all", "am", "an",
+    "and", "any", "are", "as", "at", "be", "because", "been", "before",
+    "being", "below", "between", "both", "but", "by", "can", "cannot",
+    "could", "did", "do", "does", "doing", "don", "down", "during", "each",
+    "few", "for", "from", "further", "had", "has", "have", "having", "he",
+    "her", "here", "hers", "herself", "him", "himself", "his", "how", "i",
+    "if", "in", "into", "is", "it", "its", "itself", "just", "let", "me",
+    "more", "most", "my", "myself", "no", "nor", "not", "now", "of", "off",
+    "on", "once", "only", "or", "other", "ought", "our", "ours", "ourselves",
+    "out", "over", "own", "same", "she", "should", "so", "some", "such",
+    "than", "that", "the", "their", "theirs", "them", "themselves", "then",
+    "there", "these", "they", "this", "those", "through", "to", "too",
+    "under", "until", "up", "use", "using", "very", "was", "we", "were",
+    "what", "when", "where", "which", "while", "who", "whom", "why", "will",
+    "with", "would", "you", "your", "yours", "yourself", "yourselves",
+})
+
+MAX_SIG_INPUT_CHARS: int = 4000
+_SIG_LEN: int = 16
+
+
+def _canon(items: list[str]) -> str:
+    """Canonicalize a list of tokens: sort, dedupe, join with a sentinel."""
+    return "\0".join(sorted(set(items)))
+
+
+def compute_topic_signature(
+    text: str,
+    *,
+    entity_hits: list[str] | tuple[str, ...] | None = None,
+) -> str:
+    """Compute a deterministic 16-char hex signature of ``text``.
+
+    Returns ``"0" * 16`` for empty input. Always returns exactly 16
+    lowercase hex characters.
+
+    Algorithm:
+      1. Truncate input to ``MAX_SIG_INPUT_CHARS`` (ReDoS safety).
+      2. NFC-normalize so composed/decomposed Unicode hash identically.
+      3. Extract structural tokens (identifiers, URLs, paths, quoted).
+      4. Extract word tokens (lowercased); filter stopwords + len<3.
+      5. Build bigrams over content words to resist stopword-only collisions.
+      6. Sort-dedupe each group; join; SHA-256; take first 16 hex chars.
+
+    ``entity_hits`` (LLD-13 Track C.1) — optional list of entity IDs
+    produced by the inline trigram lookup. Backward-compatible default:
+    when omitted or empty, the output is BYTE-IDENTICAL to the v3.4.21
+    pre-Living-Brain signature. When non-empty, the sorted-deduped IDs
+    are mixed into the canonical material as a seventh group so that
+    cache probes differentiate semantically-distinct prompts that
+    happen to share regex-level tokens.
+    """
+    if not text:
+        return "0" * _SIG_LEN
+
+    # 1. Hard truncation FIRST — bounds regex compute time.
+    if len(text) > MAX_SIG_INPUT_CHARS:
+        text = text[:MAX_SIG_INPUT_CHARS]
+
+    # 2. NFC normalize. Different input encodings of the same glyph now
+    # have identical codepoints before we extract or lowercase.
+    text_nfc = unicodedata.normalize("NFC", text)
+    lowered = text_nfc.lower()
+
+    # 3. Structural tokens (case-preserving — camelCase carries meaning).
+    identifiers = _CAMEL_PASCAL.findall(text_nfc)
+    urls = _URL.findall(text_nfc)
+    paths = _PATH.findall(text_nfc)
+    quoted = _QUOTED_DOUBLE.findall(text_nfc) + _QUOTED_SINGLE.findall(text_nfc)
+
+    # 4. Content words (lowered, stop-filtered, len >= 3).
+    words = _WORD.findall(lowered)
+    content_words = [w for w in words if w not in _STOPWORDS and len(w) >= 3]
+
+    # 5. Bigrams from the ORIGINAL token stream order. Preserves "foo bar"
+    # vs "bar foo" distinction and resists stopword-only differentiation.
+    bigrams = [f"{a}_{b}" for a, b in zip(content_words, content_words[1:])]
+
+    # 6. Materialize canonical form and hash.
+    groups = [
+        _canon(identifiers),
+        _canon(urls),
+        _canon(paths),
+        _canon(quoted),
+        _canon(content_words),
+        _canon(bigrams),
+    ]
+    # LLD-13: append entity-hits group ONLY when non-empty. Empty/missing
+    # preserves the byte-identical v3.4.21 pre-Living-Brain signature.
+    if entity_hits:
+        groups.append(_canon([str(e) for e in entity_hits]))
+    material = "\0\0".join(groups)
+    return hashlib.sha256(material.encode("utf-8")).hexdigest()[:_SIG_LEN]
+
+
+__all__ = ("compute_topic_signature", "MAX_SIG_INPUT_CHARS")