superlocalmemory 3.7.8 → 3.8.1

package/src/superlocalmemory/encoding/entity_resolver.py

@@ -283,22 +283,22 @@ class EntityResolver:
             entity = self._db.get_entity_by_name(name, profile_id)
             if entity is not None:
                 resolution[raw] = entity.entity_id
-                self._touch_last_seen(entity.entity_id)
+                self._touch_last_seen(entity.entity_id, profile_id)
                 continue
 
             # Tier b: alias match (case-insensitive, indexed)
             entity_id = self._alias_lookup(name, profile_id)
             if entity_id is not None:
                 resolution[raw] = entity_id
-                self._touch_last_seen(entity_id)
+                self._touch_last_seen(entity_id, profile_id)
                 continue
 
             # Tier c: fuzzy match via Jaro-Winkler
             match_id, score = self._fuzzy_match(name, profile_id)
             if match_id is not None and score >= JARO_WINKLER_AUTO_MERGE:
                 resolution[raw] = match_id
-                self._persist_alias(match_id, name, score, "jaro_winkler")
-                self._touch_last_seen(match_id)
+                self._persist_alias(match_id, name, score, "jaro_winkler", profile_id)
+                self._touch_last_seen(match_id, profile_id)
                 continue
 
             # Candidate zone (0.70–0.85): queue for LLM in Mode B/C
@@ -384,7 +384,7 @@ class EntityResolver:
         and removes the merged entity record.
         """
         # Move aliases from merge -> keep
-        aliases = self._db.get_aliases_for_entity(entity_id_merge)
+        aliases = self._db.get_aliases_for_entity(entity_id_merge, profile_id)
         for alias in aliases:
             new_alias = EntityAlias(
                 alias_id=_new_id(),
@@ -393,7 +393,7 @@ class EntityResolver:
                 confidence=alias.confidence,
                 source=f"merge_from:{entity_id_merge}",
             )
-            self._db.store_alias(new_alias)
+            self._db.store_alias(new_alias, profile_id)
 
         # Also add the merged entity's canonical name as an alias of keep
         merged = self._db.get_entity_by_name("", "")  # placeholder
@@ -403,7 +403,7 @@ class EntityResolver:
         )
         if rows:
             merged_name = str(dict(rows[0])["canonical_name"])
-            self._persist_alias(entity_id_keep, merged_name, 1.0, "merge")
+            self._persist_alias(entity_id_keep, merged_name, 1.0, "merge", profile_id)
 
         # Update atomic_facts: replace entity_id_merge with entity_id_keep
         # in canonical_entities_json column
@@ -435,14 +435,14 @@ class EntityResolver:
             except (json.JSONDecodeError, TypeError):
                 continue
 
-        # Delete the merged entity
+        # Delete the merged entity (tenant-scoped)
         self._db.execute(
-            "DELETE FROM entity_aliases WHERE entity_id = ?",
-            (entity_id_merge,),
+            "DELETE FROM entity_aliases WHERE entity_id = ? AND profile_id = ?",
+            (entity_id_merge, profile_id),
         )
         self._db.execute(
-            "DELETE FROM canonical_entities WHERE entity_id = ?",
-            (entity_id_merge,),
+            "DELETE FROM canonical_entities WHERE entity_id = ? AND profile_id = ?",
+            (entity_id_merge, profile_id),
         )
         logger.info(
             "Merged entity %s into %s (profile=%s)",
@@ -526,7 +526,7 @@ class EntityResolver:
         self._db.store_entity(entity)
 
         # Store name as its own alias for uniform lookup
-        self._persist_alias(entity.entity_id, name, 1.0, "canonical")
+        self._persist_alias(entity.entity_id, name, 1.0, "canonical", profile_id)
 
         logger.debug(
             "Created entity '%s' [%s] (type=%s, profile=%s)",
@@ -540,13 +540,16 @@ class EntityResolver:
         alias_text: str,
         confidence: float,
         source: str,
+        profile_id: str,
     ) -> None:
-        """Store an alias, skipping duplicates."""
-        # Check if alias already exists for this entity
+        """Store an alias under a profile, skipping duplicates within it."""
+        # Check if alias already exists for this entity IN THIS PROFILE. The
+        # dedup must be profile-scoped or one profile's alias suppresses
+        # another profile's identical alias for a same-id entity.
         existing = self._db.execute(
             "SELECT alias_id FROM entity_aliases "
-            "WHERE entity_id = ? AND LOWER(alias) = LOWER(?)",
-            (entity_id, alias_text),
+            "WHERE entity_id = ? AND profile_id = ? AND LOWER(alias) = LOWER(?)",
+            (entity_id, profile_id, alias_text),
         )
         if existing:
             return
@@ -557,13 +560,20 @@ class EntityResolver:
             confidence=confidence,
             source=source,
         )
-        self._db.store_alias(alias)
+        self._db.store_alias(alias, profile_id)
 
-    def _touch_last_seen(self, entity_id: str) -> None:
-        """Update last_seen timestamp on a canonical entity."""
+    def _touch_last_seen(self, entity_id: str, profile_id: str = "default") -> None:
+        """Update last_seen timestamp on a canonical entity scoped to profile.
+
+        L-01 fix: the original query had no profile_id guard. Since entity_ids are
+        UUIDs today the blast radius is theoretical, but the guard is required for
+        defense-in-depth against future import/sharing features that could introduce
+        UUID collisions across profiles.
+        """
         self._db.execute(
-            "UPDATE canonical_entities SET last_seen = ? WHERE entity_id = ?",
-            (_now(), entity_id),
+            "UPDATE canonical_entities SET last_seen = ? "
+            "WHERE entity_id = ? AND profile_id = ?",
+            (_now(), entity_id, profile_id),
         )
 
     # -- Internal: LLM disambiguation (Mode B/C) ---------------------------
@@ -621,9 +631,9 @@ class EntityResolver:
                     entity_id = known[name_str]
                     resolved[mention_str] = entity_id
                     self._persist_alias(
-                        entity_id, mention_str, 0.9, "llm",
+                        entity_id, mention_str, 0.9, "llm", profile_id,
                     )
-                    self._touch_last_seen(entity_id)
+                    self._touch_last_seen(entity_id, profile_id)
                 # If LLM says it's itself, leave for caller to create
             return resolved
 

package/src/superlocalmemory/encoding/fact_extractor.py

@@ -685,11 +685,36 @@ class FactExtractor:
                 temperature=0.0,
                 max_tokens=1024,
             )
-            return self._parse_llm_response(raw, session_id, session_date)
+            facts = self._parse_llm_response(raw, session_id, session_date)
+            return self._reflexion_refine(conversation_text, facts)
         except Exception as exc:
             logger.warning("LLM fact extraction failed: %s", exc)
             return []
 
+    def _reflexion_refine(
+        self, source_text: str, facts: list[AtomicFact],
+    ) -> list[AtomicFact]:
+        """Wave Q1: bounded, fail-open entity self-review (Mode B/C only).
+
+        Reached only from the LLM extraction path, so Mode A never runs this.
+        Any failure returns the facts unchanged.
+        """
+        if not facts or not getattr(
+            self._config, "enable_entity_reflexion", True,
+        ):
+            return facts
+        try:
+            from superlocalmemory.encoding.entity_reflexion import EntityReflexion
+
+            reflexion = EntityReflexion(
+                self._llm,
+                max_facts=getattr(self._config, "reflexion_max_facts", 8),
+            )
+            return reflexion.refine(source_text, facts)
+        except Exception as exc:
+            logger.debug("Entity reflexion skipped: %s", exc)
+            return facts
+
     def _parse_llm_response(
         self,
         raw: str,

package/src/superlocalmemory/encoding/temporal_validator.py

@@ -96,6 +96,18 @@ class TemporalValidator:
             severity = contradiction["severity"]
             reason = contradiction["description"]
 
+            # Temporal-anchor guard: if the new fact and the old fact carry
+            # distinct explicit event anchors, they describe the same subject at
+            # different times (a valid timeline — "lived in Delhi (2020)" vs
+            # "lives in Mumbai (2024)"), NOT a contradiction. Do not supersede;
+            # both stay recallable so historical queries still find them.
+            if self._is_historical_progression(new_fact, old_fact_id):
+                logger.debug(
+                    "Temporal: %s vs %s have distinct event anchors — historical "
+                    "progression, not superseding", new_fact.fact_id, old_fact_id,
+                )
+                continue
+
             # Step 1: Invalidate the old fact (bi-temporal)
             self.invalidate_fact(
                 fact_id=old_fact_id,
@@ -119,6 +131,54 @@ class TemporalValidator:
         )
         return actions
 
+    @staticmethod
+    def _event_anchor(
+        referenced_date: str | None,
+        observation_date: str | None,
+        interval_start: str | None,
+    ) -> str | None:
+        """The most-specific explicit event time, or None when undated."""
+        return referenced_date or observation_date or interval_start or None
+
+    def _is_historical_progression(
+        self, new_fact: AtomicFact, old_fact_id: str,
+    ) -> bool:
+        """True when new_fact and the old fact have distinct explicit event
+        anchors (same subject, different times) — a valid timeline rather than a
+        contradiction. Conservative: False unless BOTH anchors are present and
+        resolve to different calendar days, so undated facts supersede as before.
+        """
+        new_anchor = self._event_anchor(
+            getattr(new_fact, "referenced_date", None),
+            getattr(new_fact, "observation_date", None),
+            getattr(new_fact, "interval_start", None),
+        )
+        if not new_anchor:
+            return False
+        try:
+            rows = self._db.execute(
+                "SELECT referenced_date, observation_date, interval_start "
+                "FROM atomic_facts WHERE fact_id = ?",
+                (old_fact_id,),
+            )
+        except Exception:
+            return False
+        if not rows:
+            return False
+        d = dict(rows[0])
+        old_anchor = self._event_anchor(
+            d.get("referenced_date"), d.get("observation_date"),
+            d.get("interval_start"),
+        )
+        if not old_anchor:
+            return False
+        from superlocalmemory.retrieval.time_window import parse_timestamp
+        nd = parse_timestamp(new_anchor)
+        od = parse_timestamp(old_anchor)
+        if nd is None or od is None:
+            return False
+        return nd.date() != od.date()
+
     def detect_contradiction(
         self,
         new_fact: AtomicFact,
@@ -206,7 +266,10 @@ class TemporalValidator:
         Both params are REQUIRED in the call site. Do NOT rename to is_valid().
         """
         try:
-            tv = self._db.get_temporal_validity(fact_id)
+            # profile_id or None: an empty-string default must NOT become a
+            # `profile_id = ''` filter (which never matches → an expired fact
+            # would be reported valid). None falls back to the unscoped lookup.
+            tv = self._db.get_temporal_validity(fact_id, profile_id or None)
             if tv is None:
                 return True  # No temporal record = assumed valid
             return (

package/src/superlocalmemory/evolution/evolution_store.py

@@ -32,6 +32,7 @@ logger = logging.getLogger(__name__)
 _SCHEMA_DDL = """
 CREATE TABLE IF NOT EXISTS skill_evolution_log (
     id TEXT PRIMARY KEY,
+    profile_id TEXT NOT NULL DEFAULT 'default',
     skill_name TEXT NOT NULL,
     parent_skill_id TEXT,
     evolution_type TEXT NOT NULL,
@@ -49,14 +50,16 @@ CREATE TABLE IF NOT EXISTS skill_evolution_log (
     completed_at TEXT
 );
 
-CREATE INDEX IF NOT EXISTS idx_evo_skill ON skill_evolution_log(skill_name);
-CREATE INDEX IF NOT EXISTS idx_evo_status ON skill_evolution_log(status);
-CREATE INDEX IF NOT EXISTS idx_evo_created ON skill_evolution_log(created_at);
+CREATE INDEX IF NOT EXISTS idx_evo_skill ON skill_evolution_log(profile_id, skill_name);
+CREATE INDEX IF NOT EXISTS idx_evo_status ON skill_evolution_log(profile_id, status);
+CREATE INDEX IF NOT EXISTS idx_evo_created ON skill_evolution_log(profile_id, created_at);
 
 CREATE TABLE IF NOT EXISTS evolution_cycle_state (
-    key TEXT PRIMARY KEY,
+    profile_id TEXT NOT NULL DEFAULT 'default',
+    key TEXT NOT NULL,
     value INTEGER DEFAULT 0,
-    updated_at TEXT
+    updated_at TEXT,
+    PRIMARY KEY (profile_id, key)
 );
 """
 
@@ -77,6 +80,11 @@ class EvolutionStore:
     def _ensure_schema(self) -> None:
         conn = sqlite3.connect(self._db_path, timeout=10)
         try:
+            # Migrate an existing pre-isolation DB BEFORE running the schema DDL:
+            # the DDL creates indexes on profile_id, which would fail on a legacy
+            # table that still lacks the column. On a fresh DB the migration is a
+            # no-op (tables absent) and the DDL creates everything correctly.
+            self._migrate_profile_isolation(conn)
             conn.executescript(_SCHEMA_DDL)
             conn.commit()
         except sqlite3.OperationalError as exc:
@@ -84,56 +92,113 @@ class EvolutionStore:
         finally:
             conn.close()
 
-    def reset_cycle(self) -> None:
-        """Reset per-cycle counters. Call at start of each consolidation."""
+    def _migrate_profile_isolation(self, conn: sqlite3.Connection) -> None:
+        """Self-migrate pre-profile-isolation DBs to add per-profile scoping.
+
+        These tables are store-owned (created lazily here, not by the schema
+        migration runner which fires before this store exists), so the store
+        owns their upgrade too. Idempotent: only alters when the column/PK is
+        missing. Existing rows backfill to 'default' — the historical profile.
+        """
+        # skill_evolution_log: additive column (safe, preserves rows).
+        cols = {r[1] for r in conn.execute(
+            "PRAGMA table_info(skill_evolution_log)").fetchall()}
+        if cols and "profile_id" not in cols:
+            conn.execute(
+                "ALTER TABLE skill_evolution_log "
+                "ADD COLUMN profile_id TEXT NOT NULL DEFAULT 'default'"
+            )
+            conn.execute(
+                "CREATE INDEX IF NOT EXISTS idx_evo_skill "
+                "ON skill_evolution_log(profile_id, skill_name)"
+            )
+
+        # evolution_cycle_state: PK changes from (key) to (profile_id, key).
+        # SQLite cannot alter a PK in place → rebuild + copy, backfilling
+        # existing counters to the 'default' profile.
+        cyc_cols = {r[1] for r in conn.execute(
+            "PRAGMA table_info(evolution_cycle_state)").fetchall()}
+        if cyc_cols and "profile_id" not in cyc_cols:
+            conn.execute(
+                "ALTER TABLE evolution_cycle_state RENAME TO _evo_cycle_old"
+            )
+            conn.execute(
+                "CREATE TABLE evolution_cycle_state ("
+                " profile_id TEXT NOT NULL DEFAULT 'default',"
+                " key TEXT NOT NULL,"
+                " value INTEGER DEFAULT 0,"
+                " updated_at TEXT,"
+                " PRIMARY KEY (profile_id, key))"
+            )
+            conn.execute(
+                "INSERT INTO evolution_cycle_state "
+                "(profile_id, key, value, updated_at) "
+                "SELECT 'default', key, value, updated_at FROM _evo_cycle_old"
+            )
+            conn.execute("DROP TABLE _evo_cycle_old")
+
+    def reset_cycle(self, profile_id: str) -> None:
+        """Reset per-cycle counters for one profile. Called at cycle start.
+
+        The evolve budget is per-profile: one profile exhausting its budget
+        must never block another profile from evolving.
+        """
         now = datetime.now(timezone.utc).isoformat()
         conn = sqlite3.connect(self._db_path, timeout=10)
         try:
             conn.execute(
-                "INSERT OR REPLACE INTO evolution_cycle_state (key, value, updated_at) "
-                "VALUES ('cycle_count', 0, ?)",
-                (now,),
+                "INSERT OR REPLACE INTO evolution_cycle_state "
+                "(profile_id, key, value, updated_at) "
+                "VALUES (?, 'cycle_count', 0, ?)",
+                (profile_id, now),
             )
             conn.commit()
         finally:
             conn.close()
 
-    def can_evolve(self) -> bool:
-        """Check if budget allows another evolution this cycle."""
+    def can_evolve(self, profile_id: str) -> bool:
+        """Check if this profile's budget allows another evolution this cycle."""
         conn = sqlite3.connect(self._db_path, timeout=10)
         try:
             row = conn.execute(
-                "SELECT value FROM evolution_cycle_state WHERE key = 'cycle_count'",
+                "SELECT value FROM evolution_cycle_state "
+                "WHERE profile_id = ? AND key = 'cycle_count'",
+                (profile_id,),
             ).fetchone()
             count = row[0] if row else 0
             return count < MAX_EVOLUTIONS_PER_CYCLE
         finally:
             conn.close()
 
-    def record_evolution_attempt(self) -> None:
-        """Increment cycle counter in DB."""
+    def record_evolution_attempt(self, profile_id: str) -> None:
+        """Increment this profile's cycle counter in DB."""
         now = datetime.now(timezone.utc).isoformat()
         conn = sqlite3.connect(self._db_path, timeout=10)
         try:
             row = conn.execute(
-                "SELECT value FROM evolution_cycle_state WHERE key = 'cycle_count'",
+                "SELECT value FROM evolution_cycle_state "
+                "WHERE profile_id = ? AND key = 'cycle_count'",
+                (profile_id,),
             ).fetchone()
             current = row[0] if row else 0
             conn.execute(
-                "INSERT OR REPLACE INTO evolution_cycle_state (key, value, updated_at) "
-                "VALUES ('cycle_count', ?, ?)",
-                (current + 1, now),
+                "INSERT OR REPLACE INTO evolution_cycle_state "
+                "(profile_id, key, value, updated_at) "
+                "VALUES (?, 'cycle_count', ?, ?)",
+                (profile_id, current + 1, now),
             )
             conn.commit()
         finally:
             conn.close()
 
-    def _get_cycle_count(self) -> int:
-        """Read current cycle count from DB."""
+    def _get_cycle_count(self, profile_id: str) -> int:
+        """Read this profile's current cycle count from DB."""
         conn = sqlite3.connect(self._db_path, timeout=10)
         try:
             row = conn.execute(
-                "SELECT value FROM evolution_cycle_state WHERE key = 'cycle_count'",
+                "SELECT value FROM evolution_cycle_state "
+                "WHERE profile_id = ? AND key = 'cycle_count'",
+                (profile_id,),
             ).fetchone()
             return row[0] if row else 0
         finally:
@@ -162,18 +227,19 @@ class EvolutionStore:
     # CRUD
     # ------------------------------------------------------------------
 
-    def save_record(self, record: EvolutionRecord) -> None:
+    def save_record(self, record: EvolutionRecord, profile_id: str) -> None:
         conn = sqlite3.connect(self._db_path, timeout=10)
         try:
             conn.execute(
                 "INSERT OR REPLACE INTO skill_evolution_log "
-                "(id, skill_name, parent_skill_id, evolution_type, trigger_type, "
-                " generation, status, mutation_summary, evidence, "
+                "(id, profile_id, skill_name, parent_skill_id, evolution_type, "
+                " trigger_type, generation, status, mutation_summary, evidence, "
                 " original_content, evolved_content, content_diff, "
                 " blind_verified, rejection_reason, created_at, completed_at) "
-                "VALUES (?, ?, ?, ?, ?, ?, ?, ?, ?, ?, ?, ?, ?, ?, ?, ?)",
+                "VALUES (?, ?, ?, ?, ?, ?, ?, ?, ?, ?, ?, ?, ?, ?, ?, ?, ?)",
                 (
                     record.id,
+                    profile_id,
                     record.skill_name,
                     record.parent_skill_id,
                     record.evolution_type.value,
@@ -195,13 +261,14 @@ class EvolutionStore:
         finally:
             conn.close()
 
-    def get_record(self, record_id: str) -> Optional[EvolutionRecord]:
+    def get_record(self, record_id: str, profile_id: str) -> Optional[EvolutionRecord]:
         conn = sqlite3.connect(self._db_path, timeout=10)
         conn.row_factory = sqlite3.Row
         try:
             row = conn.execute(
-                "SELECT * FROM skill_evolution_log WHERE id = ?",
-                (record_id,),
+                "SELECT * FROM skill_evolution_log "
+                "WHERE id = ? AND profile_id = ?",
+                (record_id, profile_id),
             ).fetchone()
             if not row:
                 return None
@@ -209,68 +276,78 @@ class EvolutionStore:
         finally:
             conn.close()
 
-    def get_skill_history(self, skill_name: str, limit: int = 20) -> list[EvolutionRecord]:
+    def get_skill_history(
+        self, skill_name: str, profile_id: str, limit: int = 20,
+    ) -> list[EvolutionRecord]:
         conn = sqlite3.connect(self._db_path, timeout=10)
         conn.row_factory = sqlite3.Row
         try:
             rows = conn.execute(
                 "SELECT * FROM skill_evolution_log "
-                "WHERE skill_name = ? ORDER BY created_at DESC LIMIT ?",
-                (skill_name, limit),
+                "WHERE skill_name = ? AND profile_id = ? "
+                "ORDER BY created_at DESC LIMIT ?",
+                (skill_name, profile_id, limit),
             ).fetchall()
             return [self._row_to_record(dict(r)) for r in rows]
         finally:
             conn.close()
 
-    def get_recent(self, limit: int = 10) -> list[EvolutionRecord]:
+    def get_recent(self, profile_id: str, limit: int = 10) -> list[EvolutionRecord]:
         conn = sqlite3.connect(self._db_path, timeout=10)
         conn.row_factory = sqlite3.Row
         try:
             rows = conn.execute(
                 "SELECT * FROM skill_evolution_log "
-                "ORDER BY created_at DESC LIMIT ?",
-                (limit,),
+                "WHERE profile_id = ? ORDER BY created_at DESC LIMIT ?",
+                (profile_id, limit),
             ).fetchall()
             return [self._row_to_record(dict(r)) for r in rows]
         finally:
             conn.close()
 
-    def count_attempts(self, skill_name: str) -> int:
+    def count_attempts(self, skill_name: str, profile_id: str) -> int:
         conn = sqlite3.connect(self._db_path, timeout=10)
         try:
             row = conn.execute(
                 "SELECT COUNT(*) FROM skill_evolution_log "
-                "WHERE skill_name = ? AND status NOT IN ('promoted')",
-                (skill_name,),
+                "WHERE skill_name = ? AND profile_id = ? "
+                "AND status NOT IN ('promoted')",
+                (skill_name, profile_id),
             ).fetchone()
             return row[0] if row else 0
         finally:
             conn.close()
 
-    def has_exceeded_attempts(self, skill_name: str) -> bool:
-        return self.count_attempts(skill_name) >= MAX_ATTEMPTS_PER_SKILL
+    def has_exceeded_attempts(self, skill_name: str, profile_id: str) -> bool:
+        return self.count_attempts(skill_name, profile_id) >= MAX_ATTEMPTS_PER_SKILL
 
-    def get_stats(self) -> dict:
+    def get_stats(self, profile_id: str) -> dict:
         conn = sqlite3.connect(self._db_path, timeout=10)
         try:
             total = conn.execute(
-                "SELECT COUNT(*) FROM skill_evolution_log",
+                "SELECT COUNT(*) FROM skill_evolution_log WHERE profile_id = ?",
+                (profile_id,),
             ).fetchone()[0]
             by_status = {}
             for row in conn.execute(
-                "SELECT status, COUNT(*) FROM skill_evolution_log GROUP BY status",
+                "SELECT status, COUNT(*) FROM skill_evolution_log "
+                "WHERE profile_id = ? GROUP BY status",
+                (profile_id,),
             ).fetchall():
                 by_status[row[0]] = row[1]
             by_type = {}
             for row in conn.execute(
-                "SELECT evolution_type, COUNT(*) FROM skill_evolution_log GROUP BY evolution_type",
+                "SELECT evolution_type, COUNT(*) FROM skill_evolution_log "
+                "WHERE profile_id = ? GROUP BY evolution_type",
+                (profile_id,),
             ).fetchall():
                 by_type[row[0]] = row[1]
             return {
                 "total": total,
                 "by_status": by_status,
                 "by_type": by_type,
-                "cycle_budget_remaining": MAX_EVOLUTIONS_PER_CYCLE - self._get_cycle_count(),
+                "cycle_budget_remaining":
+                    MAX_EVOLUTIONS_PER_CYCLE - self._get_cycle_count(profile_id),
             }
         finally:
             conn.close()

package/src/superlocalmemory/evolution/llm_dispatch.py

@@ -162,7 +162,18 @@ ALLOWED_LLM_MODELS: frozenset[str] = frozenset({
 
 FORBIDDEN_MODEL_SUBSTRINGS: tuple[str, ...] = ("opus", "gpt-4-turbo")
 
-MAX_TOKENS_CAP: int = 500
+# Hard ceiling on ``max_tokens`` for any single evolution LLM call
+# (LLD-11). This is a CEILING, not a per-call default: each caller passes
+# its own budget (confirm=100, blind-verify=500, mutation=4000). The value
+# MUST stay >= the largest legitimate caller request — otherwise that call
+# trips the guard in ``_dispatch_llm`` and silently fails-closed. The
+# mutation step (``SkillEvolver._generate_mutation``) generates a full
+# SKILL.md and requests 4000; a stale 500 here made mutation return "" on
+# every cycle, killing evolution invisibly. 8000 accommodates 4000 with
+# retry/large-skill headroom. Do NOT lower below 4096 without first
+# shrinking that caller's request. Per-call spend is still bounded by
+# EvolutionBudget (10 LLM calls/cycle x 3 cycles/day).
+MAX_TOKENS_CAP: int = 8000
 
 
 # ---------------------------------------------------------------------------