thinkstack-core 4.0.0__py3-none-any.whl

thinkstack_core/reasoning_plus/learning/api.py

@@ -0,0 +1,784 @@
+"""
+thinkstack_core.reasoning_plus.learning.api
+=========================================
+High-level facade for Reasoning Plus Learning (DRPL).
+
+This is the main entry point for callers. It orchestrates:
+- recording calls
+- extracting learnings
+- retrieving relevant learnings
+- composing prompt blocks
+- applying outcome feedback
+"""
+from __future__ import annotations
+
+import json
+from pathlib import Path
+from typing import Any, Callable
+
+import logging
+
+from thinkstack_core.reasoning_plus.config import ReasoningPlusConfig
+from thinkstack_core.reasoning_plus.learning.composer import PromptComposer
+from thinkstack_core.reasoning_plus.learning.embeddings import (
+    EmbeddingBackend,
+    KeywordEmbeddingBackend,
+    get_embedding_backend,
+)
+from thinkstack_core.reasoning_plus.learning.context_collector import (
+    ExtractionContext,
+    collect_extraction_context,
+)
+from thinkstack_core.reasoning_plus.learning.conflicts import (
+    Conflict,
+    ConflictDetector,
+    ConflictResolution,
+    resolve_conflict,
+)
+from thinkstack_core.reasoning_plus.learning.evolution import (
+    apply_confidence_decay,
+    goal_changed_since,
+)
+from thinkstack_core.reasoning_plus.learning.extractor import (
+    LearningExtractor,
+    make_extractor,
+)
+from thinkstack_core.reasoning_plus.learning.pii import (
+    filter_learnings_for_sync,
+    sanitize_for_extraction,
+    scan_for_secrets,
+)
+from thinkstack_core.reasoning_plus.learning.models import Learning, ReasoningCall, _make_id
+from thinkstack_core.reasoning_plus.learning.provenance import ProvenanceRecord, ProvenanceStore, _hash_prompt
+from thinkstack_core.reasoning_plus.learning.recorder import CallRecorder
+from thinkstack_core.reasoning_plus.learning.relevance import RelevanceEngine
+from thinkstack_core.reasoning_plus.learning.state import workspace_state_hash
+from thinkstack_core.reasoning_plus.learning.store import LearningStore, _atomic_json_write
+from thinkstack_core.reasoning_plus.learning import cross_project
+
+logger = logging.getLogger("thinkstack.reasoning_plus.learning")
+
+
+LLMClient = Callable[[str], str]
+
+
+class ReasoningPlusLearning:
+    """
+    Facade for learning from reasoning and feeding it back into future calls.
+
+    Usage:
+        drpl = ReasoningPlusLearning(gcc_dir, repo_path)
+        call_id = drpl.record_call(
+            call_type="tool",
+            name="read_file",
+            reasoning="Reading utils.py because the error mentions parse_date.",
+            outcome="failure",
+            input="utils.py",
+            output="...",
+            state_hash=drpl.workspace_hash(),
+            session_id="session-1",
+        )
+        drpl.extract_learnings(call_id)
+        learnings = drpl.get_relevant_learnings("Fix the parse_date bug")
+        prompt = drpl.compose_user_prompt("Fix the parse_date bug", learnings)
+    """
+
+    def __init__(
+        self,
+        gcc_dir: Path | str,
+        repo_path: Path | str | None = None,
+        config: ReasoningPlusConfig | None = None,
+        llm_client: Callable[[str], str] | None = None,
+    ) -> None:
+        self._gcc_dir = Path(gcc_dir)
+        self._repo_path = Path(repo_path) if repo_path else self._gcc_dir.parent
+        self._config = config or ReasoningPlusConfig()
+        self._llm_client = llm_client
+
+        self._recorder = CallRecorder(self._gcc_dir)
+        self._store = LearningStore(self._gcc_dir)
+        self._provenance = ProvenanceStore(self._gcc_dir)
+        self._extractor = self._make_extractor()
+        self._relevance = RelevanceEngine(
+            backend=self._make_backend(),
+            cache_ttl=self._config.learning_relevance_cache_ttl,
+        )
+        self._composer = PromptComposer(max_lines=self._config.learning_max_lines)
+
+        # Batch extraction queue: call_id -> ExtractionContext
+        self._pending_extractions: dict[str, ExtractionContext] = {}
+        self._batch_threshold: int = getattr(self._config, "learning_batch_threshold", 5)
+
+        # Conflict detector reuses the embedding backend for similarity scoring.
+        self._conflict_detector = ConflictDetector(backend=self._relevance._backend)
+
+    def _make_extractor(self) -> LearningExtractor:
+        """Build the configured learning extractor, falling back to rule-based on errors."""
+        try:
+            return make_extractor(
+                strategy=self._config.learning_extraction_strategy,
+                llm_client=self._llm_client,
+            )
+        except Exception as exc:
+            logger.warning(
+                "thinkstack: failed to load learning extractor strategy '%s' — %s; falling back to rule-based",
+                self._config.learning_extraction_strategy,
+                exc,
+            )
+            return LearningExtractor()
+
+    def _make_backend(self) -> EmbeddingBackend:
+        """Build the configured embedding backend, falling back to keyword on errors."""
+        try:
+            return get_embedding_backend(
+                self._config.learning_embedding_backend,
+                self._config.learning_embedding_model,
+                max_keywords=self._config.max_keywords,
+            )
+        except Exception as exc:
+            logger.warning(
+                "thinkstack: failed to load embedding backend '%s' — %s; falling back to keyword",
+                self._config.learning_embedding_backend,
+                exc,
+            )
+            return KeywordEmbeddingBackend(max_keywords=self._config.max_keywords)
+
+    # ------------------------------------------------------------------
+    # Recording
+    # ------------------------------------------------------------------
+
+    def record_call(self, *, call_type: str, reasoning: str, session_id: str = "", name: str = "", input: str = "", output: str = "", outcome: str = "unknown", state_hash: str = "", concepts: list[str] | None = None, confidence: float = 1.0, sensitivity: str = "PUBLIC", scope: str = "project", meta: dict[str, Any] | None = None, call_id: str | None = None) -> str:
+        """Record a single call and return its ID."""
+        call = ReasoningCall(
+            id=call_id or _make_id("call"),
+            call_type=call_type,
+            name=name,
+            reasoning=reasoning,
+            input=input,
+            output=output,
+            outcome=outcome,
+            state_hash=state_hash or self.workspace_hash(),
+            concepts=concepts or [],
+            confidence=confidence,
+            sensitivity=sensitivity,
+            scope=scope,
+            session_id=session_id,
+            meta=meta or {},
+        )
+        self._recorder.record(call)
+        return call.id
+
+    def record_and_extract(self, *, call_type: str, reasoning: str, session_id: str = "", outcome: str = "unknown", **kwargs: Any) -> tuple[str, list[str]]:
+        """Record a call and immediately extract learnings from it."""
+        call_id = self.record_call(
+            call_type=call_type,
+            reasoning=reasoning,
+            session_id=session_id,
+            outcome=outcome,
+            **kwargs,
+        )
+        learning_ids = self.extract_learnings(call_id)
+        return call_id, learning_ids
+
+    # ------------------------------------------------------------------
+    # Extraction
+    # ------------------------------------------------------------------
+
+    def _apply_disclosure_gate(self, call: ReasoningCall) -> bool:
+        """Return True if the call passes the configured disclosure policy gate."""
+        policy = getattr(self._config, "disclosure_policy", "standard")
+        if policy == "strict" and call.sensitivity != "PUBLIC":
+            return False
+        if policy == "standard" and call.sensitivity == "PRIVATE":
+            return False
+        return True
+
+    def _extract_and_scan(
+        self,
+        call: ReasoningCall,
+        context: ExtractionContext,
+    ) -> list[str]:
+        """Extract learnings from a call, sanitize PII, scan for secrets, store.
+
+        Shared by both synchronous (extract_learnings) and batch (extract_batch)
+        paths so PII guardrails are never bypassed.
+        """
+        if not self._apply_disclosure_gate(call):
+            return []
+
+        call = ReasoningCall.from_dict(call.to_dict())
+        call.reasoning = sanitize_for_extraction(call.reasoning)
+
+        learnings = self._extractor.extract(call, context=context)
+
+        ids: list[str] = []
+        for learning in learnings:
+            secrets = scan_for_secrets(learning.content)
+            if secrets:
+                logger.warning(
+                    "thinkstack: quarantined learning %s — matched secret types: %s",
+                    learning.id, ",".join(secrets),
+                )
+                self._log_quarantine(learning, secrets)
+                continue
+            self._store.save(learning)
+            ids.append(learning.id)
+        return ids
+
+    def extract_learnings(self, call_id: str) -> list[str]:
+        """Extract and store learnings from a recorded call immediately.
+
+        Applies disclosure policy gating, PII sanitization on reasoning text,
+        and secret scanning on extracted learnings. For batch extraction with
+        LLM gating, use ``queue_extraction()`` instead.
+        """
+        call = self._recorder.get(call_id)
+        if not call:
+            return []
+
+        if not self._apply_disclosure_gate(call):
+            return []
+
+        context = collect_extraction_context(call, gcc_dir=self._gcc_dir)
+        return self._extract_and_scan(call, context)
+
+    def queue_extraction(self, call_id: str) -> list[str]:
+        """Queue a call for batch extraction.
+
+        When the queue reaches ``learning_batch_threshold``, a batch extraction
+        is triggered automatically. Returns learning IDs if batch was triggered,
+        or empty list if still queued.
+        """
+        call = self._recorder.get(call_id)
+        if not call:
+            return []
+
+        # Disclosure policy gating (S20).
+        policy = getattr(self._config, "disclosure_policy", "standard")
+        if policy == "strict" and call.sensitivity != "PUBLIC":
+            return []
+        if policy == "standard" and call.sensitivity == "PRIVATE":
+            return []
+
+        context = collect_extraction_context(call, gcc_dir=self._gcc_dir)
+        if not context.is_significant():
+            return []
+
+        self._pending_extractions[call_id] = context
+
+        if len(self._pending_extractions) >= self._batch_threshold:
+            return self.extract_batch()
+
+        return []
+
+    def extract_batch(self) -> list[str]:
+        """Extract all queued calls in a single batch.
+
+        Reduces per-call LLM extraction cost by combining multiple calls into
+        one extraction pass. PII guardrails are applied via the shared
+        ``_extract_and_scan`` helper. Can be called explicitly at session end.
+        """
+        if not self._pending_extractions:
+            return []
+
+        call_ids = list(self._pending_extractions.keys())
+        contexts = list(self._pending_extractions.values())
+        self._pending_extractions.clear()
+
+        learning_ids: list[str] = []
+        for call_id, context in zip(call_ids, contexts):
+            call = self._recorder.get(call_id)
+            if not call:
+                continue
+            try:
+                learning_ids.extend(self._extract_and_scan(call, context))
+            except Exception as exc:
+                logger.warning("thinkstack: batch extraction failed for call %s — %s", call_id, exc)
+
+        return learning_ids
+
+    def flush_extractions(self) -> list[str]:
+        """Flush any pending extractions now (called at session end)."""
+        if not self._pending_extractions:
+            return []
+        return self.extract_batch()
+
+    @property
+    def pending_extraction_count(self) -> int:
+        """Number of calls queued for batch extraction."""
+        return len(self._pending_extractions)
+
+    # ------------------------------------------------------------------
+    # Retrieval
+    # ------------------------------------------------------------------
+
+    def get_relevant_learnings(
+        self,
+        context: str,
+        top_n: int | None = None,
+        state_hash: str | None = None,
+    ) -> list[Learning]:
+        """Return the most relevant active learnings for the given context."""
+        if not self._config.learning_enabled:
+            return []
+        top_n = top_n or self._config.learning_top_n
+        all_active = self._store.list(validity="active")
+        return self._relevance.rank(
+            context,
+            all_active,
+            current_state_hash=state_hash or self.workspace_hash(),
+            top_n=top_n,
+        )
+
+    def cross_project_suggest(self, query: str, top_n: int = 3) -> list[Learning]:
+        """Return relevant learnings from sibling governed projects.
+
+        Looks up the machine-level registry of governed projects, finds projects
+        whose name or tags overlap with the query, loads their active learnings,
+        and returns the top-N most relevant ones.
+        """
+        if not self._config.learning_enabled:
+            return []
+        return cross_project.cross_project_suggest(
+            query=query,
+            current_project_root=self._repo_path,
+            top_n=top_n,
+        )
+
+    # ------------------------------------------------------------------
+    # Cross-project & org learning (S21)
+    # ------------------------------------------------------------------
+
+    def get_cross_project_learnings(
+        self,
+        context: str,
+        top_n: int | None = None,
+        apply_filter: bool = True,
+    ) -> list[Learning]:
+        """Return org-scope learnings from sibling projects, five-layer filtered."""
+        if not self._config.learning_cross_project_enabled:
+            return []
+
+        top_n = top_n if top_n is not None else self._config.learning_cross_project_top_n
+        candidates = cross_project.cross_project_suggest(
+            query=context,
+            current_project_root=self._repo_path,
+            top_n=top_n * 2,
+        )
+        if not apply_filter:
+            return candidates[:top_n]
+
+        from thinkstack_core.reasoning_plus.learning.filter_five_layer import five_layer_filter
+        from thinkstack_core.reasoning_plus.learning.deny_list import load_deny_list
+
+        deny_list = load_deny_list(self._repo_path)
+        from thinkstack_core.reasoning_plus.context import extract_keywords
+        ctx_emb = self._relevance._backend.encode(context)
+        ctx_kw = set(extract_keywords(context, max_keywords=30))
+        state = self.workspace_hash()
+        filtered: list[Learning] = []
+        for learning in candidates:
+            relevance = self._relevance._score(learning, ctx_emb, state, ctx_kw)
+            allowed, _reason = five_layer_filter(
+                learning,
+                target_project_root=self._repo_path,
+                prompt_context=context,
+                relevance_score=relevance,
+                deny_list=deny_list,
+                min_relevance=self._config.learning_relevance_threshold,
+            )
+            if allowed:
+                filtered.append(learning)
+            if len(filtered) >= top_n:
+                break
+        return filtered
+
+    def get_combined_learnings(
+        self,
+        context: str,
+        top_n: int | None = None,
+        state_hash: str | None = None,
+    ) -> list[Learning]:
+        """Return project-local + org learning recommendations, co-ranked.
+
+        Org learnings are pulled first, then merged with local learnings,
+        and the combined set is ranked by the RelevanceEngine.
+        """
+        local = self.get_relevant_learnings(
+            context=context,
+            top_n=top_n,
+            state_hash=state_hash,
+        )
+        if not self._config.learning_cross_project_enabled:
+            return local
+
+        cross = self.get_cross_project_learnings(
+            context=context,
+            top_n=min(self._config.learning_max_org_learnings_per_call, top_n or 5),
+        )
+        if not cross:
+            return local
+
+        existing_ids = {l.id for l in local}
+        combined = list(local)
+        for learning in cross:
+            if learning.id not in existing_ids:
+                combined.append(learning)
+
+        top = top_n or self._config.learning_top_n
+        return self._relevance.rank(
+            context, combined, current_state_hash=state_hash or self.workspace_hash(), top_n=top,
+        )
+
+    def promote_learning(
+        self,
+        learning_id: str,
+        to_scope: str = "org",
+        promoted_by: str | None = None,
+    ) -> Learning | None:
+        """Promote a learning to org scope, making it available cross-project."""
+        from thinkstack_core.reasoning_plus.learning.promotion import \
+            promote_learning as _promote
+        return _promote(
+            learning_id=learning_id,
+            gcc_dir=self._gcc_dir,
+            to_scope=to_scope,
+            promoted_by=promoted_by or "cli",
+        )
+
+    def learning_search(
+        self,
+        query: str,
+        search_type: str | None = None,
+        scope: str | None = None,
+        top_n: int = 10,
+    ) -> list[Learning]:
+        """Search learnings by concept, type, scope, or full-text.
+
+        Searches both the project-local store and the org aggregate.
+        """
+        results: list[Learning] = []
+        all_local = self._store.list(validity="active")
+        for learning in all_local:
+            if self._match_learning(learning, query, search_type, scope):
+                results.append(learning)
+
+        if self._config.learning_cross_project_enabled:
+            import os
+            from thinkstack_core.reasoning_plus.learning.cross_project import (
+                DEFAULT_REGISTRY_DIR,
+                DEFAULT_REGISTRY_FILE,
+                REGISTRY_PATH_ENV,
+            )
+            from thinkstack_core.reasoning_plus.learning.org_store import \
+                aggregate_org_learnings
+            env_path = os.environ.get(REGISTRY_PATH_ENV, "").strip()
+            if env_path:
+                registry_path = Path(env_path)
+            else:
+                registry_path = DEFAULT_REGISTRY_DIR / DEFAULT_REGISTRY_FILE
+            orgs = aggregate_org_learnings(registry_path)
+            for org in orgs:
+                dummy = Learning(
+                    content=org.content,
+                    type=org.type,
+                    trigger_concepts=org.trigger_concepts,
+                    validity=org.validity,
+                    confidence=org.confidence,
+                    scope=org.scope,
+                    sensitivity=org.sensitivity,
+                )
+                if self._match_learning(dummy, query, search_type, scope):
+                    results.append(dummy)
+
+        return sorted(results, key=lambda l: l.confidence, reverse=True)[:top_n]
+
+    @staticmethod
+    def _match_learning(
+        learning: Learning,
+        query: str,
+        search_type: str | None,
+        scope: str | None,
+    ) -> bool:
+        q = query.lower()
+        if search_type and learning.type != search_type:
+            return False
+        if scope and learning.scope != scope:
+            return False
+        if q in learning.content.lower():
+            return True
+        for concept in learning.trigger_concepts:
+            if q in concept.lower():
+                return True
+        return False
+
+    # ------------------------------------------------------------------
+    # Composition
+    # ------------------------------------------------------------------
+
+    def compose_user_prompt(self, user_prompt: str, learnings: list[Learning]) -> str:
+        """Append a compact <learnings> block to the user prompt.
+
+        The block is capped at ``learning_token_budget`` tokens and filtered
+        by ``learning_relevance_threshold`` confidence, both from config.
+        """
+        block = self._composer.compose(
+            learnings,
+            token_budget=self._config.learning_token_budget,
+            relevance_threshold=self._config.learning_relevance_threshold,
+        )
+        if not block:
+            return user_prompt
+        return f"{user_prompt}\n\n{block}"
+
+    def compose_system_prompt(self, system_prompt: str, learnings: list[Learning]) -> str:
+        """Append a learning appendix to the system prompt (fallback)."""
+        block = self._composer.compose_system_prompt(learnings)
+        if not block:
+            return system_prompt
+        return f"{system_prompt}\n\n{block}"
+
+    # ------------------------------------------------------------------
+    # Feedback
+    # ------------------------------------------------------------------
+
+    def apply_feedback(self, learning_id: str, outcome: str) -> Learning | None:
+        """Adjust confidence or validity based on observed outcome."""
+        learning = self._store.get(learning_id)
+        if not learning:
+            return None
+
+        if outcome == "success":
+            learning.confidence = min(1.0, learning.confidence + 0.1)
+        elif outcome == "failure":
+            learning.confidence = max(0.0, learning.confidence - 0.2)
+            if learning.confidence < 0.3:
+                learning.validity = "deprecated"
+        elif outcome == "stale":
+            learning.validity = "stale"
+
+        learning.updated_at = _now_iso()
+        self._store.save(learning)
+        return learning
+
+    # ------------------------------------------------------------------
+    # Conflict resolution & evolution
+    # ------------------------------------------------------------------
+
+    def detect_and_resolve_conflicts(
+        self,
+        incoming: Learning,
+        existing: list[Learning] | None = None,
+    ) -> list[ConflictResolution]:
+        """Detect conflicts between ``incoming`` and existing learnings, then resolve them.
+
+        For each conflict the resolution matrix decides:
+        - ``NEWER_WINS``: older learning deprecated (``superseded_by`` set),
+          newer learning records it in ``supersedes``.
+        - ``OLDER_WINS``: newer learning marked stale; its content appended
+          as a note to the older learning.
+        - ``FLAG_FOR_HUMAN``: conflict persisted to
+          ``.GCC/reasoning_learnings/conflicts/`` for manual resolution.
+
+        Returns the list of :class:`ConflictResolution` objects.
+        """
+        if existing is None:
+            existing = self._store.list(validity="active")
+        # Exclude the incoming learning itself from the candidate set.
+        existing = [l for l in existing if l.id != incoming.id]
+
+        goal_changed = goal_changed_since(incoming.id, self._gcc_dir)
+        conflicts = self._conflict_detector.detect_conflicts(incoming, existing)
+        resolutions: list[ConflictResolution] = []
+
+        for conflict in conflicts:
+            conflict.goal_changed = goal_changed
+            res = resolve_conflict(conflict)
+            self._apply_resolution(res)
+            if not res.auto_resolved:
+                self._persist_conflict(conflict, res)
+            resolutions.append(res)
+
+        return resolutions
+
+    def _apply_resolution(self, res: ConflictResolution) -> None:
+        """Mutate the losing/winning learnings on disk per the resolution.
+
+        All in-memory mutations are applied before any disk write so that each
+        learning is saved exactly once with its final state.
+        """
+        if res.action == "NEWER_WINS":
+            older = self._store.get(res.loser)
+            newer = self._store.get(res.winner)
+            # Apply all mutations in memory first.
+            if older and newer:
+                if older.id not in newer.supersedes:
+                    newer.supersedes = list(newer.supersedes) + [older.id]
+                if not newer.evolution_chain:
+                    newer.evolution_chain = f"chain-{newer.id[:12]}"
+                older.evolution_chain = newer.evolution_chain
+            if older:
+                older.validity = "deprecated"
+                older.superseded_by = res.winner
+                older.updated_at = _now_iso()
+                self._store.save(older, deduplicate=False)
+            if newer and older:
+                newer.updated_at = _now_iso()
+                self._store.save(newer, deduplicate=False)
+        elif res.action == "OLDER_WINS":
+            newer = self._store.get(res.loser)
+            older = self._store.get(res.winner)
+            # Apply all mutations in memory first.
+            if older and newer:
+                note = newer.short_form(max_chars=160)
+                existing_notes = older.meta.get("notes", "")
+                if note not in existing_notes:
+                    older.meta["notes"] = f"{existing_notes} | superseded attempt: {note}".strip(" |")
+                    older.updated_at = _now_iso()
+            if newer:
+                newer.validity = "stale"
+                newer.updated_at = _now_iso()
+                self._store.save(newer, deduplicate=False)
+            if older and newer:
+                self._store.save(older, deduplicate=False)
+        # FLAG_FOR_HUMAN: no learning mutation; persistence handled by caller.
+
+    def _persist_conflict(self, conflict: Conflict, res: ConflictResolution) -> None:
+        """Write a human-reviewable conflict record to .GCC/."""
+        conflicts_dir = self._gcc_dir / "reasoning_learnings" / "conflicts"
+        conflicts_dir.mkdir(parents=True, exist_ok=True)
+        record = {
+            "learning_a": conflict.learning_a.id,
+            "learning_b": conflict.learning_b.id,
+            "concept_overlap": conflict.concept_overlap,
+            "embedding_similarity": conflict.embedding_similarity,
+            "confidence_a": conflict.confidence_a,
+            "confidence_b": conflict.confidence_b,
+            "goal_changed": conflict.goal_changed,
+            "action": res.action,
+            "reason": res.reason,
+            "resolved": False,
+            "timestamp": _now_iso(),
+        }
+        path = conflicts_dir / f"conflict_{conflict.learning_a.id}_{conflict.learning_b.id}.json"
+        try:
+            _atomic_json_write(path, record)
+        except Exception as exc:
+            logger.warning("thinkstack: failed to persist conflict record — %s", exc)
+
+    def list_conflicts(self) -> list[dict[str, Any]]:
+        """Return all persisted unresolved conflict records."""
+        conflicts_dir = self._gcc_dir / "reasoning_learnings" / "conflicts"
+        if not conflicts_dir.exists():
+            return []
+        out: list[dict[str, Any]] = []
+        for path in sorted(conflicts_dir.glob("*.json")):
+            try:
+                record = json.loads(path.read_text(encoding="utf-8"))
+                if record.get("resolved"):
+                    continue
+                out.append(record)
+            except Exception as exc:
+                logger.debug("thinkstack: skipping malformed conflict %s — %s", path, exc)
+        return out
+
+    def _log_quarantine(self, learning: Learning, secrets: list[str]) -> None:
+        """Log a quarantined learning event to .GCC/events.log.jsonl.
+
+        The content preview is redacted before logging so secrets that
+        triggered the quarantine are never written to the audit log.
+        """
+        events_path = self._gcc_dir / "events.log.jsonl"
+        try:
+            record = {
+                "type": "LEARNING_QUARANTINED",
+                "learning_id": learning.id,
+                "secrets": secrets,
+                "content_preview": sanitize_for_extraction(learning.content[:120]),
+                "timestamp": _now_iso(),
+            }
+            with open(events_path, "a", encoding="utf-8") as f:
+                f.write(json.dumps(record) + "\n")
+        except Exception as exc:
+            logger.warning("thinkstack: failed to log quarantine event — %s", exc)
+
+    def apply_confidence_decay_sweep(self) -> list[str]:
+        """Apply confidence decay to all active learnings.
+
+        Returns the list of learning IDs that were modified (decayed or staled).
+        """
+        changed: list[str] = []
+        for learning in self._store.list(validity="active"):
+            before_conf = learning.confidence
+            before_val = learning.validity
+            apply_confidence_decay(learning)
+            if learning.confidence != before_conf or learning.validity != before_val:
+                self._store.save(learning, deduplicate=False)
+                changed.append(learning.id)
+        return changed
+
+    # ------------------------------------------------------------------
+    # Provenance
+    # ------------------------------------------------------------------
+
+    def record_injection(
+        self,
+        learning_ids: list[str],
+        *,
+        call_id: str,
+        session_id: str = "",
+        prompt_text: str = "",
+        model_name: str = "",
+    ) -> ProvenanceRecord:
+        """Record that a set of learnings was injected into a call."""
+        record = ProvenanceRecord(
+            call_id=call_id,
+            learning_ids=learning_ids,
+            session_id=session_id,
+            prompt_hash=_hash_prompt(prompt_text),
+            prompt_excerpt=prompt_text[:200],
+            model_name=model_name,
+        )
+        self._provenance.save(record)
+        return record
+
+    def record_injection_outcome(self, call_id: str, outcome: str) -> None:
+        """Update provenance for a call and apply feedback to injected learnings."""
+        record = self._provenance.update_outcome(call_id, outcome)
+        if not record:
+            return
+        for learning_id in record.learning_ids:
+            try:
+                self.apply_feedback(learning_id, outcome)
+            except Exception as exc:
+                logger.warning("thinkstack: feedback failed for learning %s — %s", learning_id, exc)
+
+    def get_provenance(self, call_id: str) -> ProvenanceRecord | None:
+        """Return the provenance record for a call, if any."""
+        return self._provenance.get_by_call(call_id)
+
+    def list_provenance(self, learning_id: str | None = None) -> list[ProvenanceRecord]:
+        """Return provenance records, optionally filtered by learning."""
+        return self._provenance.list(learning_id=learning_id)
+
+    def invalidate_stale(self, changed_paths: list[str]) -> list[str]:
+        """Mark learnings affected by the given changed paths as stale."""
+        from thinkstack_core.reasoning_plus.learning.state import affected_by_state_change
+        invalidated: list[str] = []
+        for learning in self._store.list(validity="active"):
+            if affected_by_state_change(self._repo_path, learning.trigger_concepts, changed_paths):
+                self._store.invalidate(learning.id, reason="stale")
+                invalidated.append(learning.id)
+        return invalidated
+
+    # ------------------------------------------------------------------
+    # State
+    # ------------------------------------------------------------------
+
+    def workspace_hash(self, file_paths: list[str] | None = None) -> str:
+        return workspace_state_hash(self._repo_path, file_paths)
+
+
+def _now_iso() -> str:
+    from datetime import datetime, timezone
+    return datetime.now(timezone.utc).isoformat()