superlocalmemory 4.1.13 → 4.1.15

package/src/superlocalmemory/evolution/blind_verifier.py

@@ -1,122 +0,0 @@
-# Copyright (c) 2026 Varun Pratap Bhardwaj / Qualixar
-# Licensed under AGPL-3.0-or-later - see LICENSE file
-# Part of SuperLocalMemory V3 | https://qualixar.com | https://varunpratap.com
-
-"""Blind Verifier — information-isolated skill verification.
-
-The key insight from EvoSkills (arXiv:2604.01687): when a generator
-creates a skill and the same model verifies it, confirmation bias is
-nearly guaranteed. The verifier must be BLIND to the generator's reasoning.
-
-This verifier:
-- Uses a DIFFERENT model from the generator (Haiku vs Sonnet)
-- CANNOT see: original skill, mutation rationale, generator's reasoning
-- CAN see: task description (what the skill should do), evolved SKILL.md
-- Evaluates independently: "Does this skill correctly address the task?"
-
-Part of Qualixar | Author: Varun Pratap Bhardwaj
-"""
-
-from __future__ import annotations
-
-import json
-import logging
-import re
-from dataclasses import dataclass
-from typing import Optional
-
-logger = logging.getLogger(__name__)
-
-
-@dataclass(frozen=True)
-class VerificationResult:
-    """Result of blind verification."""
-    passed: bool
-    confidence: float  # 0.0-1.0
-    issues: tuple[str, ...] = ()
-    reasoning: str = ""
-
-
-def build_verification_prompt(
-    skill_name: str,
-    skill_description: str,
-    evolved_content: str,
-) -> str:
-    """Build blind verification prompt.
-
-    The verifier sees ONLY:
-    - What the skill is supposed to do (name + description)
-    - The evolved skill content
-
-    The verifier does NOT see:
-    - The original skill
-    - Why it was evolved
-    - What evidence triggered evolution
-    - The generator's reasoning
-    """
-    return f"""You are an independent skill quality reviewer. You have NOT seen the original
-version of this skill or why it was modified. Evaluate it purely on its merits.
-
-SKILL PURPOSE: {skill_name}
-EXPECTED BEHAVIOR: {skill_description}
-
-SKILL CONTENT TO REVIEW:
-{evolved_content[:8000]}
-
-EVALUATE:
-1. Does the skill clearly explain what to do? (clarity)
-2. Are the instructions specific and actionable? (specificity)
-3. Are there any obvious errors, contradictions, or missing steps? (correctness)
-4. Would an AI agent be able to follow these instructions? (executability)
-
-RESPOND IN JSON FORMAT:
-{{
-  "passed": true/false,
-  "confidence": 0.0-1.0,
-  "issues": ["issue1", "issue2"],
-  "reasoning": "brief explanation"
-}}
-
-Be strict. Only pass skills that are genuinely clear, correct, and actionable.
-A mediocre skill that might work sometimes should FAIL — evolution should produce
-clear improvements, not marginal changes."""
-
-
-def parse_verification_response(response: str) -> VerificationResult:
-    """Parse the verifier's JSON response."""
-    # Try parsing JSON from response
-    json_match = re.search(r"\{[^{}]*\"passed\"[^{}]*\}", response, re.DOTALL)
-    if json_match:
-        try:
-            data = json.loads(json_match.group(0))
-            return VerificationResult(
-                passed=bool(data.get("passed", False)),
-                confidence=float(data.get("confidence", 0.5)),
-                issues=tuple(data.get("issues", [])),
-                reasoning=str(data.get("reasoning", "")),
-            )
-        except (json.JSONDecodeError, TypeError, ValueError):
-            pass
-
-    # Fallback: keyword detection.
-    # Negative keywords are checked first so that negating phrases such as
-    # "cannot approve" or "not approved" are never mistakenly matched by the
-    # positive keyword "approve".
-    lower = response.lower()
-    if any(kw in lower for kw in (
-        "\"passed\": false", "passed: false",
-        "reject", "fail",
-        "cannot approve", "not approve",
-    )):
-        return VerificationResult(passed=False, confidence=0.6, reasoning="keyword match")
-
-    if any(kw in lower for kw in ("\"passed\": true", "passed: true", "approve", "looks good")):
-        return VerificationResult(passed=True, confidence=0.6, reasoning="keyword match")
-
-    # Default: reject if can't parse (conservative)
-    return VerificationResult(
-        passed=False,
-        confidence=0.3,
-        reasoning="Could not parse verification response",
-        issues=("Unparseable response",),
-    )

package/src/superlocalmemory/evolution/budget.py

@@ -1,356 +0,0 @@
-# Copyright (c) 2026 Varun Pratap Bhardwaj / Qualixar
-# Licensed under AGPL-3.0-or-later - see LICENSE file
-# Part of SuperLocalMemory v3.4.22 — LLD-11 §Budget
-
-"""Evolution budget enforcement.
-
-Hard caps per MASTER-PLAN §4.4 + LLD-11:
-  - Wall-time per cycle: 30 minutes (1800 seconds)
-  - LLM calls per cycle: 10
-  - Cycles per day per profile: 3
-  - Single-flight via per-profile lock file resolved with
-    ``safe_resolve_identifier`` (LLD-00 §4)
-
-All four constraints are non-negotiable — crossing any of them raises
-``BudgetExhausted`` so the caller can abort the cycle safely without
-poisoning ``action_outcomes`` or the recall pipeline.
-
-Author: Varun Pratap Bhardwaj / Qualixar
-"""
-
-from __future__ import annotations
-
-import logging
-import os
-import sqlite3
-import time
-import uuid
-from contextlib import contextmanager
-from datetime import datetime, timezone
-from pathlib import Path
-from typing import Iterator
-
-from superlocalmemory.core.security_primitives import safe_resolve_identifier
-
-logger = logging.getLogger(__name__)
-
-try:  # POSIX advisory locks (macOS/Linux)
-    import fcntl as _fcntl
-except ImportError:  # Windows has no fcntl; use its stdlib byte-range lock.
-    _fcntl = None
-
-
-def _acquire_profile_lock(fd: int) -> None:
-    """Acquire a non-blocking cross-process lock on every supported OS."""
-    if _fcntl is not None:
-        _fcntl.flock(fd, _fcntl.LOCK_EX | _fcntl.LOCK_NB)
-        return
-
-    import msvcrt
-
-    # ``msvcrt.locking`` cannot lock an empty file. Reserve one marker byte;
-    # the file content is diagnostic only and never a correctness signal.
-    if os.fstat(fd).st_size == 0:
-        os.write(fd, b"\0")
-    os.lseek(fd, 0, os.SEEK_SET)
-    try:
-        msvcrt.locking(fd, msvcrt.LK_NBLCK, 1)
-    except OSError as exc:
-        raise BlockingIOError("evolution profile lock is held") from exc
-
-
-def _release_profile_lock(fd: int) -> None:
-    """Release the lock acquired by :func:`_acquire_profile_lock`."""
-    if _fcntl is not None:
-        _fcntl.flock(fd, _fcntl.LOCK_UN)
-        return
-
-    import msvcrt
-
-    os.lseek(fd, 0, os.SEEK_SET)
-    msvcrt.locking(fd, msvcrt.LK_UNLCK, 1)
-
-
-# M-P-07: path-component hints for filesystems where advisory locking is
-# known to degrade to a no-op. We do NOT abort — some users accept the
-# risk — but we emit a one-shot warning so a double-cycle is at least
-# attributable to a known root cause. If/when we ship a threading-only
-# fallback, this list becomes the trigger for switching modes.
-_SYNC_ROOT_HINTS: tuple[str, ...] = (
-    "iCloud Drive",
-    "Library/Mobile Documents",       # macOS iCloud backing store
-    "OneDrive",
-    "Dropbox",
-    "Google Drive",
-    "pCloudDrive",
-)
-_WARNED_SYNC_PATHS: set[str] = set()
-
-
-def _detect_sync_root(path: Path) -> str | None:
-    """Return the matching sync-root hint if ``path`` lives under one."""
-    try:
-        parts = tuple(path.resolve().parts)
-    except Exception:  # pragma: no cover — path resolution failures
-        parts = path.parts
-    joined = "/".join(parts)
-    for hint in _SYNC_ROOT_HINTS:
-        if hint in joined:
-            return hint
-    return None
-
-
-# ---------------------------------------------------------------------------
-# Contract constants (non-negotiable per MASTER-PLAN §4.4)
-# ---------------------------------------------------------------------------
-
-MAX_WALL_TIME_SEC: int = 1800        # 30 minutes per cycle
-MAX_LLM_CALLS_PER_CYCLE: int = 10    # 10 LLM calls per cycle
-MAX_CYCLES_PER_DAY: int = 3          # 3 cycles per profile per UTC day
-
-
-class BudgetExhausted(RuntimeError):
-    """Raised when a budget dimension is crossed.
-
-    The ``dimension`` attribute records which cap was hit so callers can
-    log structured metrics without string-parsing the message.
-    """
-
-    def __init__(self, dimension: str, detail: str = "") -> None:
-        self.dimension = dimension
-        suffix = f": {detail}" if detail else ""
-        super().__init__(f"budget exhausted [{dimension}]{suffix}")
-
-
-class EvolutionBudget:
-    """Per-profile, per-cycle budget gate.
-
-    Usage::
-
-        budget = EvolutionBudget(profile_id="default",
-                                 learning_db=Path("~/.slm/learning.db"),
-                                 lock_dir=Path("~/.superlocalmemory"))
-        with budget.cycle():
-            budget.check_time()
-            budget.charge_llm_call()
-            ...
-
-    The ``cycle()`` context manager acquires a single-flight lock (via
-    ``safe_resolve_identifier`` on the profile name) and enforces the
-    3-cycles-per-day cap. Inside the cycle, callers must call
-    ``check_time()`` before each expensive step and ``charge_llm_call()``
-    before each LLM dispatch.
-    """
-
-    def __init__(
-        self,
-        *,
-        profile_id: str,
-        learning_db: Path | str,
-        lock_dir: Path | str,
-    ) -> None:
-        self._profile_id = profile_id
-        self._learning_db = Path(learning_db)
-        self._lock_dir = Path(lock_dir)
-        self._lock_dir.mkdir(parents=True, exist_ok=True)
-        # Resolve lock path through the LLD-00 §4 safe helper so a malicious
-        # profile_id cannot escape the lock directory. The helper regex
-        # rejects '.' so we hand it the identifier portion only, then
-        # append the fixed ``.lock`` suffix to the validated path.
-        safe_stem = safe_resolve_identifier(
-            self._lock_dir, f"evolution-{profile_id}",
-        )
-        self._lock_path = safe_stem.with_suffix(".lock")
-        # M-P-07: warn once per lock-path when we detect the lock sits on
-        # a known sync-backed filesystem. Advisory locking silently
-        # degrades on iCloud/OneDrive/Dropbox — two concurrent cycles
-        # would each acquire and burn LLM budget. Documentation-only for
-        # now; a future release may refuse to run until the lock_dir is
-        # moved off the sync root.
-        try:
-            root_hint = _detect_sync_root(self._lock_path)
-        except Exception:  # pragma: no cover — defensive
-            root_hint = None
-        if root_hint is not None:
-            key = str(self._lock_path)
-            if key not in _WARNED_SYNC_PATHS:
-                _WARNED_SYNC_PATHS.add(key)
-                logger.warning(
-                    "evolution lock at %s lives under %r — advisory locking "
-                    "may silently no-op on sync-backed filesystems. "
-                    "Concurrent cycles could double-bill LLM cost. Move "
-                    "the lock_dir off the sync root to make single-flight "
-                    "enforceable.",
-                    key, root_hint,
-                )
-
-        self._cycle_start_mono: float | None = None
-        self._llm_calls_this_cycle: int = 0
-        self._lock_fd: int | None = None
-
-    # ------------------------------------------------------------------
-    # Per-day cycle accounting (sqlite-backed via evolution_config.last_cycle_at
-    # + cycles_this_week; today-count is derived from last_cycle_at day)
-    # ------------------------------------------------------------------
-
-    def _count_cycles_today(self) -> int:
-        """Count cycles recorded for ``profile_id`` on the current UTC day.
-
-        Reads from ``evolution_llm_cost_log`` — ``cycle_id`` distinct values
-        scoped to today. Evolution cycles stamp a ``cycle_id`` on every
-        cost-log row they emit, so distinct cycle_ids == distinct cycles.
-
-        A cycle with zero LLM calls still needs to count; the budget stamps
-        a zero-row sentinel via ``_record_cycle_start`` on acquire.
-        """
-        today = datetime.now(timezone.utc).strftime("%Y-%m-%d")
-        conn = sqlite3.connect(self._learning_db)
-        try:
-            row = conn.execute(
-                "SELECT COUNT(DISTINCT cycle_id) "
-                "FROM evolution_llm_cost_log "
-                "WHERE profile_id=? AND substr(ts,1,10)=? "
-                "  AND cycle_id IS NOT NULL",
-                (self._profile_id, today),
-            ).fetchone()
-            return int(row[0]) if row and row[0] is not None else 0
-        finally:
-            conn.close()
-
-    def _record_cycle_start(self, cycle_id: str) -> None:
-        """Write a sentinel row so this cycle is counted toward the daily cap.
-
-        Tokens/cost are zero — the real LLM cost rows land as
-        ``charge_llm_call`` is invoked by the dispatcher.
-
-        H-16 (Stage 8): profile_id must be a non-empty string. Enforced
-        here so a mis-constructed EvolutionBudget fails at the first
-        write instead of silently attributing cost to an empty bucket.
-        """
-        if not isinstance(self._profile_id, str) or not self._profile_id.strip():
-            raise ValueError(
-                "EvolutionBudget.profile_id must be a non-empty string "
-                f"(got {self._profile_id!r})"
-            )
-        now = datetime.now(timezone.utc).isoformat(timespec="seconds")
-        conn = sqlite3.connect(self._learning_db)
-        try:
-            conn.execute(
-                "INSERT INTO evolution_llm_cost_log "
-                "(profile_id, ts, model, tokens_in, tokens_out, cost_usd, cycle_id) "
-                "VALUES (?,?,?,?,?,?,?)",
-                (self._profile_id, now, "cycle-start", 0, 0, 0.0, cycle_id),
-            )
-            conn.commit()
-        finally:
-            conn.close()
-
-    # ------------------------------------------------------------------
-    # Public runtime checks
-    # ------------------------------------------------------------------
-
-    def check_time(self) -> None:
-        """Raise ``BudgetExhausted`` if wall-time cap exceeded."""
-        if self._cycle_start_mono is None:
-            raise RuntimeError("check_time() called outside cycle()")
-        elapsed = time.monotonic() - self._cycle_start_mono
-        if elapsed > MAX_WALL_TIME_SEC:
-            raise BudgetExhausted(
-                "wall_time",
-                f"elapsed {elapsed:.1f}s > {MAX_WALL_TIME_SEC}s",
-            )
-
-    def charge_llm_call(self) -> None:
-        """Charge one LLM call toward the per-cycle cap.
-
-        Raises ``BudgetExhausted`` AFTER the cap is already exhausted.
-        Call this BEFORE dispatching the LLM so the cap is protective.
-        """
-        if self._cycle_start_mono is None:
-            raise RuntimeError("charge_llm_call() called outside cycle()")
-        if self._llm_calls_this_cycle >= MAX_LLM_CALLS_PER_CYCLE:
-            raise BudgetExhausted(
-                "llm_calls",
-                f"charged {self._llm_calls_this_cycle} "
-                f"(cap {MAX_LLM_CALLS_PER_CYCLE})",
-            )
-        self._llm_calls_this_cycle += 1
-
-    # ------------------------------------------------------------------
-    # Context manager — single-flight + daily cap + wall-time init
-    # ------------------------------------------------------------------
-
-    @contextmanager
-    def cycle(self, cycle_id: str | None = None) -> Iterator["EvolutionBudget"]:
-        """Acquire single-flight lock + enforce daily cap + start wall timer."""
-        # Daily cap check BEFORE taking the lock — a blocked cycle must
-        # not hold the file lock while other cycles wait.
-        today_count = self._count_cycles_today()
-        if today_count >= MAX_CYCLES_PER_DAY:
-            raise BudgetExhausted(
-                "cycles_per_day",
-                f"profile={self._profile_id} today={today_count} "
-                f"cap={MAX_CYCLES_PER_DAY}",
-            )
-
-        # Single-flight lock (non-blocking advisory lock). A second concurrent
-        # acquire raises BlockingIOError — surface as BudgetExhausted.
-        fd = os.open(str(self._lock_path), os.O_CREAT | os.O_RDWR, 0o600)
-        try:
-            try:
-                _acquire_profile_lock(fd)
-            except BlockingIOError as e:
-                os.close(fd)
-                raise BudgetExhausted(
-                    "single_flight",
-                    f"another cycle holds {self._lock_path}",
-                ) from e
-            self._lock_fd = fd
-        except BudgetExhausted:
-            raise
-        except Exception:
-            try:
-                os.close(fd)
-            except OSError:
-                pass
-            raise
-
-        # Write pid marker (best-effort, never fails the acquire).
-        try:
-            os.write(fd, f"{os.getpid()}:{self._profile_id}\n".encode())
-        except OSError:
-            pass
-
-        cid = cycle_id or (
-            datetime.now(timezone.utc).strftime("cyc-%Y%m%d-%H%M%S-")
-            + uuid.uuid4().hex[:8]
-        )
-        try:
-            self._record_cycle_start(cid)
-        except sqlite3.Error as e:
-            # Release lock before propagating — a failed cycle-record should
-            # not leave the lock dangling.
-            try:
-                _release_profile_lock(fd)
-            finally:
-                os.close(fd)
-                self._lock_fd = None
-            raise RuntimeError(
-                f"failed to record cycle start: {e}",
-            ) from e
-
-        self._cycle_start_mono = time.monotonic()
-        self._llm_calls_this_cycle = 0
-
-        try:
-            yield self
-        finally:
-            self._cycle_start_mono = None
-            try:
-                _release_profile_lock(fd)
-            finally:
-                try:
-                    os.close(fd)
-                except OSError:
-                    pass
-                self._lock_fd = None