ct-toolkit 0.3.7__tar.gz → 0.3.8__tar.gz

{ct_toolkit-0.3.7 → ct_toolkit-0.3.8}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: ct-toolkit
-Version: 0.3.7
+Version: 0.3.8
 Summary: Computational Theseus Toolkit — Identity Continuity Guardrails for Agentic Systems
 Author: Hakan Damar
 License: Apache-2.0

{ct_toolkit-0.3.7 → ct_toolkit-0.3.8}/ct_toolkit/__init__.py

@@ -23,7 +23,7 @@ from ct_toolkit.core.exceptions import (
     ChainIntegrityError,
 )
 
-__version__ = "0.3.7"
+__version__ = "0.3.8"
 
 __all__ = [
     "TheseusWrapper",

{ct_toolkit-0.3.7 → ct_toolkit-0.3.8}/ct_toolkit/core/exceptions.py

@@ -85,6 +85,22 @@ class CriticalDivergenceError(DivergenceError):
         )
 
 
+class CriticalSandboxDivergenceError(DivergenceError):
+    """
+    Raised when a sandbox (staged) agent exhibits critical divergence during cooldown.
+    The staged kernel update is rejected and the sandbox is torn down.
+    """
+    def __init__(self, endorsement_id: str, l1_score: float | None, reason: str):
+        self.endorsement_id = endorsement_id
+        self.l1_score = l1_score
+        self.reason = reason
+        super().__init__(
+            f"Sandbox agent for staged endorsement '{endorsement_id[:8]}...' exhibited "
+            f"critical divergence during cooldown (score={l1_score}, reason={reason!r}). "
+            "Staged update rejected and sandbox torn down."
+        )
+
+
 # ── Provenance Errors ────────────────────────────────────────────────────────
 
 class ProvenanceError(CTToolkitError):

{ct_toolkit-0.3.7 → ct_toolkit-0.3.8}/ct_toolkit/core/wrapper.py

@@ -16,23 +16,33 @@ In the background:
   2. Each request/response is written to the Provenance Log with HMAC signature.
   3. Embedding cosine similarity (L1 ECS) is calculated.
   4. If the threshold is exceeded, L2/L3 is triggered.
+  5. Staged Approval (Cooldown): Risky kernel updates are monitored via shadow requests
+     before being promoted to production.
 """
 from __future__ import annotations
 
 import time
-import hashlib
 import os
 from dataclasses import dataclass, field
 from pathlib import Path
-from typing import Any, Iterator, Optional, Callable, Dict
+from typing import Any, Optional, Callable, Dict, List
+
 import litellm
 
 from ct_toolkit.core.kernel import ConstitutionalKernel
 from ct_toolkit.core.compatibility import CompatibilityLayer, CompatibilityResult
-from ct_toolkit.core.exceptions import CTToolkitError, MissingClientError
+from ct_toolkit.core.exceptions import (
+    MissingClientError, 
+    CriticalSandboxDivergenceError
+)
 from ct_toolkit.core.integrity import IntegrityMonitor
 from ct_toolkit.divergence.scheduler import RiskProfile
 from ct_toolkit.core.compression_guard import ContextCompressionGuard
+from ct_toolkit.endorsement.reflective import (
+    ReflectiveEndorsement, 
+    StagedUpdateManager,
+    CooldownCalculator
+)
 from ct_toolkit.utils.logger import get_logger
 
 logger = get_logger(__name__)
@@ -74,6 +84,11 @@ class WrapperConfig:
     compression_threshold: float = 0.85
     compression_passive_detection: bool = True
 
+    # -- Staged Approval (Cooldown) --
+    endorsement_cooldown_base: int = CooldownCalculator.DEFAULT_BASE_SECONDS
+    endorsement_cooldown_max: int = CooldownCalculator.DEFAULT_MAX_SECONDS
+    endorsement_no_probe_penalty: int = CooldownCalculator.DEFAULT_NO_PROBE_PENALTY_S
+
 
 @dataclass
 class CTResponse:
@@ -85,6 +100,8 @@ class CTResponse:
     divergence_tier: str | None = None      # "ok" | "l1_warning" | "l2_judge" | "l3_icm"
     provenance_id: str | None = None
     raw_response: Any = field(default=None, repr=False)
+    # Sandbox metadata if staged updates are active
+    sandbox_divergence: float | None = None
 
     def __str__(self) -> str:
         return self.content
@@ -125,15 +142,6 @@ class TheseusWrapper:
     ) -> None:
         """
         Initializes TheseusWrapper.
-        
-        Args:
-            client:  An existing API client instance (OpenAI, Anthropic, etc.).
-                    Optional if 'provider' is specified.
-            config:  Optional WrapperConfig instance.
-            provider: Provider name (e.g. "openai", "anthropic", "ollama", "google", "cohere").
-                      If provided, LiteLLM will be used to initialize the client internally.
-            project_root: Path to the user's project root directory. Used to find a custom 'config/' folder.
-                          Defaults to the current working directory.
         """
         self._config = config or WrapperConfig(
             kernel_path=kernel_path,
@@ -175,6 +183,9 @@ class TheseusWrapper:
         )
         self._shadow_history: Optional[List[Dict[str, str]]] = None
 
+        # ── Staged Approval (Cooldown) ──
+        self._staged_manager = StagedUpdateManager()
+
         # ── Integrity Monitoring ──
         self._integrity_monitor = IntegrityMonitor()
         self._register_monitored_files()
@@ -183,8 +194,7 @@ class TheseusWrapper:
 
     def _register_monitored_files(self):
         """
-        Finds and registers all critical configuration files for integrity monitoring,
-        including both built-in package files and user-provided custom configs.
+        Finds and registers all critical configuration files for integrity monitoring.
         """
         logger.debug("Registering configuration files for integrity monitoring.")
         
@@ -205,10 +215,7 @@ class TheseusWrapper:
                         self._integrity_monitor.register_file(file_path)
 
         except Exception:
-            # Fallback for older Python or different environments
             package_root = Path(__file__).parent.parent
-            # This is less ideal as it might find non-package files, but it's a
-            # reasonable fallback for development environments.
             for pattern in internal_patterns:
                 for file_path in package_root.rglob(pattern):
                     if file_path.is_file():
@@ -229,23 +236,16 @@ class TheseusWrapper:
     # ── Factory / Init ─────────────────────────────────────────────────────────
 
     def _detect_provider(self, client: Any) -> str:
-        """
-        Detects the provider from the client instance or string.
-        Returns 'unknown' if detection fails.
-        """
         if client is None:
             return "unknown"
             
         if isinstance(client, str):
-            # client passed as a string (e.g. "openai")
             return client.lower()
 
         try:
-            # Check for LiteLLM specific attributes if any
             if hasattr(client, "provider") and isinstance(client.provider, str):
                 return client.provider
 
-            # Check module name
             module = type(client).__module__.lower()
             if "openai" in module: return "openai"
             if "anthropic" in module: return "anthropic"
@@ -258,21 +258,18 @@ class TheseusWrapper:
         return "unknown"
 
     def _load_kernel(self) -> ConstitutionalKernel:
-        # 1. Check for explicit path
         if self._config.kernel_path:
             logger.debug(f"Loading kernel from explicit path: {self._config.kernel_path}")
             return ConstitutionalKernel.from_yaml(self._config.kernel_path)
 
         safe_name = os.path.basename(self._config.kernel_name)
         
-        # 2. Check for user-defined config directory
         if self._project_root:
             user_config_path = self._project_root / "config" / f"{safe_name}.yaml"
             if user_config_path.exists():
                 logger.debug(f"Loading kernel from user config: {user_config_path}")
                 return ConstitutionalKernel.from_yaml(user_config_path)
 
-        # 3. Load built-in kernel using importlib.resources
         try:
             from importlib.resources import files
             kernel_resource = files("ct_toolkit.kernels").joinpath(f"{safe_name}.yaml")
@@ -280,7 +277,6 @@ class TheseusWrapper:
                 logger.debug(f"Loading built-in kernel: {safe_name}.yaml")
                 return ConstitutionalKernel.from_yaml(kernel_resource)
         except (ImportError, FileNotFoundError):
-            # Fallback for older python versions
             kernel_path = (
                 Path(__file__).parent.parent
                 / "kernels"
@@ -296,7 +292,6 @@ class TheseusWrapper:
         return ConstitutionalKernel.default()
 
     def _init_provenance_log(self) -> Any:
-        """Initializes the Provenance Log vault adapter (Will be fully implemented in Step 2)."""
         from ct_toolkit.provenance.log import ProvenanceLog
         return ProvenanceLog(
             vault_type=self._config.vault_type,
@@ -304,13 +299,10 @@ class TheseusWrapper:
         )
 
     def _init_identity_layer(self) -> Any:
-        """Initializes the Identity Embedding Layer."""
         from ct_toolkit.identity.embedding import IdentityEmbeddingLayer
         
-        # Guard against using raw clients that don't support embeddings
         emb_client = self._config.embedding_client
         if emb_client is None:
-            # Only default to main client if it's known to be OpenAI (standard for embeddings)
             if self._provider == "openai":
                 emb_client = self._client
             else:
@@ -325,7 +317,6 @@ class TheseusWrapper:
         )
 
     def _init_divergence_engine(self) -> Any:
-        """Initializes the Divergence Engine (judge_client is required for L2/L3)."""
         from ct_toolkit.divergence.engine import DivergenceEngine
         from ct_toolkit.divergence.scheduler import ElasticityScheduler
         
@@ -383,15 +374,10 @@ class TheseusWrapper:
     ) -> CTResponse:
         """
         Sends a single message, returning the response with identity protection.
-
-        Args:
-            message:  User message
-            model:    Model to use (provider default is used)
-            system:   Additional system prompt (appended to kernel)
-            history:  Conversation history [{"role": ..., "content": ...}]
         """
         # --- Pre-flight Checks ---
         self._integrity_monitor.verify_integrity()
+        self._process_staged_updates()
 
         composed_system = self._compose_system_prompt(system)
         messages = self._build_messages(message, history, composed_system)
@@ -449,6 +435,11 @@ class TheseusWrapper:
                 
             break
 
+        # --- Staged Approval Monitoring (Shadow Requests) ---
+        sandbox_divergence = None
+        if self._staged_manager.has_active_staged():
+            sandbox_divergence = self._run_shadow_requests(message, history, model, **kwargs)
+
         # Provenance Log record
         provenance_id = None
         if self._config.log_requests:
@@ -464,6 +455,7 @@ class TheseusWrapper:
                     "template": self._config.template,
                     "kernel": self._kernel.name,
                     "drift_alert_enabled": self._config.drift_alert_callback is not None,
+                    "sandbox_divergence": sandbox_divergence,
                 },
             )
 
@@ -475,8 +467,99 @@ class TheseusWrapper:
             divergence_tier=div_result.tier.value,
             provenance_id=provenance_id,
             raw_response=raw_response,
+            sandbox_divergence=sandbox_divergence,
         )
 
+    # ── Shadow Request Logic ──────────────────────────────────────────────────
+
+    def _run_shadow_requests(
+        self,
+        message: str,
+        history: list[dict[str, str]] | None,
+        model: str | None,
+        **kwargs: Any,
+    ) -> float | None:
+        """
+        Runs the interaction against one or more 'staged' (sandbox) kernels
+        to observe if the proposed changes cause identity drift.
+        """
+        active_staged = self._staged_manager.get_active()
+        if not active_staged:
+            return None
+
+        # To keep it simple, we monitor the first active staged update
+        staged_record = active_staged[0]
+        
+        # 1. Clone current kernel and apply the staged rule
+        sandbox_kernel = ConstitutionalKernel.from_dict(self._kernel.to_dict())
+        try:
+            sandbox_kernel.update_commitment(
+                staged_record.commitment_id, 
+                staged_record.rule_text
+            )
+        except Exception as e:
+            logger.error(f"Failed to apply staged rule to sandbox kernel: {e}")
+            return None
+
+        # 2. Call provider with sandbox kernel
+        sandbox_system = sandbox_kernel.get_system_prompt_injection()
+        sandbox_messages = self._build_messages(message, history, sandbox_system)
+        
+        try:
+            # We use the same model/client as the live request
+            sandbox_response = self._call_provider(sandbox_messages, model=model, **kwargs)
+            sandbox_content = self._extract_content(sandbox_response)
+            
+            # 3. Analyze sandbox divergence
+            sandbox_div_score = self._identity_layer.compute_divergence(sandbox_content)
+            
+            # 4. Critical Divergence Check
+            if sandbox_div_score >= self._config.divergence_l3_threshold:
+                reason = f"Sandbox divergence L1 score {sandbox_div_score:.4f} exceeded L3 threshold."
+                self._staged_manager.reject_staged(staged_record.id, reason=reason)
+                raise CriticalSandboxDivergenceError(
+                    endorsement_id=staged_record.id,
+                    l1_score=sandbox_div_score,
+                    reason=reason
+                )
+            
+            return sandbox_div_score
+
+        except CriticalSandboxDivergenceError:
+            raise
+        except Exception as e:
+            logger.warning(f"Shadow request for staged update failed: {e}")
+            return None
+
+    def _process_staged_updates(self) -> None:
+        """
+        Checks for staged updates whose cooldown has expired and
+        promotes them to the production kernel.
+        """
+        promotable = self._staged_manager.get_promotable()
+        for record in promotable:
+            try:
+                logger.info(
+                    f"Promoting staged endorsement to production: {record.id[:8]}... "
+                    f"rule='{record.rule_text}'"
+                )
+                self._kernel.update_commitment(record.commitment_id, record.rule_text)
+                
+                # Write promotion event to log
+                if self._config.log_requests:
+                    self._provenance_log.record(
+                        request_text=f"[COOLDOWN_EXPIRED] Promoting staged rule",
+                        response_text=f"Rule applied to production kernel: {record.rule_text}",
+                        metadata={
+                            "event_type": "staged_promotion",
+                            "endorsement_id": record.id,
+                            "kernel": self._kernel.name,
+                            "commitment_id": record.commitment_id,
+                        }
+                    )
+            except Exception as e:
+                logger.error(f"Failed to promote staged update {record.id[:8]}: {e}")
+
     # ── Provider Dispatch ──────────────────────────────────────────────────────
 
     def _has_env_credentials(self) -> bool:
@@ -487,7 +570,6 @@ class TheseusWrapper:
         if self._provider == "anthropic":
             return bool(os.environ.get("ANTHROPIC_API_KEY"))
         if self._provider == "ollama":
-            # Ollama typically doesn't need a key locally
             return True
         if self._provider == "google":
             return bool(os.environ.get("GOOGLE_API_KEY"))
@@ -500,44 +582,32 @@ class TheseusWrapper:
         **kwargs: Any,
     ) -> Any:
         """Uses LiteLLM for unified provider calling."""
-        # --- Passive Context Compression Detection ---
         if self._config.compression_passive_detection and self._shadow_history:
-            # Simple heuristic: message count dropped significantly
-            # We use 0.7 as a threshold (30% drop)
             if len(messages) < len(self._shadow_history) * 0.7:
                 self._compression_guard.on_passive_detection(
                     original=self._shadow_history,
                     compressed=messages
                 )
 
-        # Update shadow history for next call
         self._shadow_history = list(messages)
         
-        # LiteLLM handles different message formats internally
-        
-        # Set default models per provider if not specified
         if not model:
             if self._provider == "openai": model = "gpt-4o-mini"
             elif self._provider == "anthropic": model = "claude-3-5-sonnet-latest"
             elif self._provider == "ollama": model = "llama3"
             else: model = "gpt-4o-mini"
 
-        # LiteLLM expects "provider/model" format for non-default providers
-        # Usually OpenAI models don't need a prefix.
         full_model = model
         if ":" in model:
-             # If it has the legacy format "provider:model", convert it
              full_model = model.replace(":", "/", 1)
         elif self._provider not in ("openai", "unknown"):
              full_model = f"{self._provider}/{model}"
 
-        # Extract connection info from client if possible
         if hasattr(self._client, "base_url") and self._client.base_url:
             kwargs["api_base"] = str(self._client.base_url)
         if hasattr(self._client, "api_key") and self._client.api_key:
             kwargs["api_key"] = self._client.api_key
 
-        # Transfer common client configurations if available
         if hasattr(self._client, "timeout") and "timeout" not in kwargs:
             kwargs["timeout"] = self._client.timeout
 
@@ -552,7 +622,6 @@ class TheseusWrapper:
     def _compose_system_prompt(self, extra: str | None) -> str:
         kernel_injection = self._kernel.get_system_prompt_injection()
         
-        # If this kernel contains propagated constraints, add a specific header
         if any(a.id.startswith("propagated_") for a in self._kernel.anchors):
             kernel_injection = (
                 "# Mother Agent Constraints\n"
@@ -568,13 +637,11 @@ class TheseusWrapper:
     def propagate_headers(self) -> dict[str, str]:
         """
         Returns a dictionary of headers to be used when calling sub-agents.
-        Includes the current kernel serialized for propagation.
         """
         import json
         import base64
         
         kernel_data = self._kernel.to_dict()
-        # Mark as read-only for sub-agents
         kernel_data["is_readonly"] = True
         
         encoded_kernel = base64.b64encode(json.dumps(kernel_data).encode()).decode()
@@ -598,31 +665,26 @@ class TheseusWrapper:
         return messages
 
     def _extract_content(self, raw: Any) -> str:
-        # Handle dict responses
         if isinstance(raw, dict):
             if "choices" in raw and isinstance(raw["choices"], list) and raw["choices"]:
                 return raw["choices"][0].get("message", {}).get("content", "") or ""
             if "message" in raw:
-                # Ollama dictate format
                 return raw["message"].get("content", "") or ""
             return str(raw)
 
-        # LiteLLM ModelResponse (Standardized for all providers)
         try:
             if hasattr(raw, "choices") and raw.choices:
                 choice = raw.choices[0]
                 if hasattr(choice, "message") and choice.message:
                     return choice.message.content or ""
-                # Some older/alternative formats
                 if hasattr(choice, "text"):
                     return choice.text or ""
         except Exception:
             pass
             
-        # Fallback raw extraction for edge cases
-        if hasattr(raw, "content") and isinstance(raw.content, list): # Anthropic style
+        if hasattr(raw, "content") and isinstance(raw.content, list):
              return raw.content[0].text if raw.content else ""
-        if hasattr(raw, "message"): # Ollama generic style
+        if hasattr(raw, "message"):
              return getattr(raw.message, "content", "") or ""
              
         return str(raw)
@@ -635,7 +697,6 @@ class TheseusWrapper:
         return fallback or "unknown"
 
     def _run_divergence_engine(self, message: str, response: str, interaction_count: int = 0, skip_l3: bool = False) -> Any:
-        """Runs the staged divergence engine (L1 -> L2 -> L3)."""
         try:
             return self._divergence_engine.analyze(message, response, interaction_count, skip_l3=skip_l3)
         except Exception as e:
@@ -649,10 +710,6 @@ class TheseusWrapper:
     # ── Kernel Management ────────────────────────────────────────────────────────
 
     def validate_user_rule(self, rule_text: str) -> None:
-        """
-        Validates a user-defined rule against the kernel.
-        Raises an exception if there is a conflict.
-        """
         self._kernel.validate_user_rule(rule_text)
 
     def endorse_rule(
@@ -664,15 +721,7 @@ class TheseusWrapper:
     ) -> Any:
         """
         Validates the rule; initiates the Reflective Endorsement
-        flow if there is a plastic conflict. Throws hard reject on axiomatic violation.
-
-        Args:
-            rule_text:            The rule to be enforced
-            operator_id:          The identity of the person granting approval
-            approval_channel:     Custom approval channel (default: CLI)
-            commitment_new_value: New value to assign to the commitment
-
-        Returns: EndorsementRecord
+        flow if there is a plastic conflict.
         """
         from ct_toolkit.endorsement.reflective import ReflectiveEndorsement
 
@@ -680,6 +729,11 @@ class TheseusWrapper:
             kernel=self._kernel,
             provenance_log=self._provenance_log,
             approval_channel=approval_channel,
+            staged_manager=self._staged_manager,
+            cooldown_base_s=self._config.endorsement_cooldown_base,
+            cooldown_max_s=self._config.endorsement_cooldown_max,
+            no_probe_penalty_s=self._config.endorsement_no_probe_penalty,
+            template=self._config.template,
         )
         return re.validate_and_endorse(
             rule_text=rule_text,
@@ -688,18 +742,6 @@ class TheseusWrapper:
         )
 
     def export_provenance_log(self) -> list[dict[str, Any]]:
-        """
-        Exports the entire verified provenance log.
-
-        Verifies the integrity of the log before returning the data.
-        This is intended for external auditing and analysis.
-
-        Returns:
-            A list of all log entries as dictionaries.
-
-        Raises:
-            ChainIntegrityError: If the log's hash chain is broken.
-        """
         return self._provenance_log.export_log()
 
     @property
@@ -714,6 +756,10 @@ class TheseusWrapper:
     def divergence_engine(self) -> Any:
         return self._divergence_engine
 
+    @property
+    def staged_manager(self) -> StagedUpdateManager:
+        return self._staged_manager
+
     def __repr__(self) -> str:
         return (
             f"TheseusWrapper("

{ct_toolkit-0.3.7 → ct_toolkit-0.3.8}/ct_toolkit/divergence/l3_icm.py

@@ -230,6 +230,40 @@ class ICMRunner:
             "ollama":    "llama3",
         }.get(provider, "gpt-4o-mini")
 
+    # ── Probe Availability Check ────────────────────────────────────────────
+
+    @staticmethod
+    def has_probes(
+        template: str,
+        kernel_name: str,  # noqa: ARG004  (reserved for future kernel-specific probes)
+        project_root: Path | None = None,
+    ) -> bool:
+        """
+        Returns True if any probe files exist for the given template/kernel combination.
+        Does NOT run the probes — intended as a fast pre-flight check for cooldown
+        duration calculation in the Reflective Endorsement protocol.
+
+        Probe availability order (mirrors _load_probes):
+          1. base_probes.json — always counts as available
+          2. user config: <project_root>/config/<template>_probes.json
+          3. built-in domain: endorsement/probes/domain_probes/<template>_probes.json
+        """
+        probes_dir = ICMRunner.PROBES_DIR
+
+        # Base probes are always present; if they exist, we consider probes available.
+        if (probes_dir / "base_probes.json").exists():
+            return True
+
+        # Check user-supplied domain probes
+        if project_root:
+            user_probe_path = project_root / "config" / f"{template}_probes.json"
+            if user_probe_path.exists():
+                return True
+
+        # Check built-in domain probes
+        domain_path = probes_dir / "domain_probes" / f"{template}_probes.json"
+        return domain_path.exists()
+
     # ── Main Runner ────────────────────────────────────────────────────────
 
     def run(self) -> ICMReport:

{ct_toolkit-0.3.7 → ct_toolkit-0.3.8}/ct_toolkit/endorsement/reflective.py

@@ -7,9 +7,14 @@ Flow:
   1. User-defined rule conflicts with kernel → PlasticConflictError is caught
   2. ConflictRecord is created — conflict details are documented
   3. User is directed to approval channel (CLI / callback / API)
-  4. If user approves → EndorsementRecord is signed, written to Provenance Log
-  5. Kernel is updated, system continues to operate
-  6. If user rejects → system remains unchanged, rejection record written to log
+  4. Decision options:
+     a. APPROVED  → EndorsementRecord signed, kernel updated immediately
+     b. STAGED    → EndorsementRecord signed, kernel update deferred to cooldown period.
+                    A sandbox agent (cloned kernel) observes shadow traffic.
+                    After cooldown expires without violations → kernel updated.
+                    If CriticalDivergenceError during cooldown → REJECTED.
+     c. REJECTED  → System remains unchanged, rejection record written to log
+  5. All decisions are written to the Provenance Log.
 
 Each override is additionally monitored in subsequent ICM tests (flagged=True).
 """
@@ -37,6 +42,7 @@ class EndorsementDecision(str, Enum):
     REJECTED = "rejected"
     PENDING  = "pending"
     FAILED   = "failed"
+    STAGED   = "staged"    # Approved conditionally — pending cooldown observation
 
 
 @dataclass
@@ -64,7 +70,7 @@ class ConflictRecord:
 
 @dataclass
 class EndorsementRecord:
-    """Signed record of user approval/rejection decision."""
+    """Signed record of user approval/rejection/staged decision."""
     id: str
     timestamp: float
     conflict_id: str
@@ -74,6 +80,10 @@ class EndorsementRecord:
     operator_id: str                # Who approved / rejected
     rationale: str                  # Why it was approved / rejected
     kernel_name: str
+    # Cooldown fields (only set for STAGED decisions)
+    cooldown_duration_s: int | None = None   # Total cooldown window in seconds
+    cooldown_until: float | None = None       # Epoch timestamp when cooldown ends
+    probe_available: bool = True             # Whether probes were available for this kernel/template
     content_hash: str = field(default="", repr=False)
 
     def __post_init__(self) -> None:
@@ -91,12 +101,27 @@ class EndorsementRecord:
             "operator_id": self.operator_id,
             "rationale": self.rationale,
             "kernel_name": self.kernel_name,
+            "cooldown_duration_s": self.cooldown_duration_s,
+            "cooldown_until": self.cooldown_until,
+            "probe_available": self.probe_available,
         }, sort_keys=True)
         return hashlib.sha256(payload.encode()).hexdigest()
 
+    @property
+    def is_staged(self) -> bool:
+        return self.decision == EndorsementDecision.STAGED
+
+    @property
+    def is_cooldown_expired(self) -> bool:
+        """True if this is a STAGED record whose cooldown period has elapsed."""
+        if not self.is_staged or self.cooldown_until is None:
+            return False
+        deadline: float = self.cooldown_until  # narrowed: not None
+        return time.time() >= deadline
+
     def to_provenance_metadata(self) -> dict[str, Any]:
         """Metadata to be written to Provenance Log."""
-        return {
+        meta: dict[str, Any] = {
             "event_type": "reflective_endorsement",
             "endorsement_id": self.id,
             "conflict_id": self.conflict_id,
@@ -106,8 +131,188 @@ class EndorsementRecord:
             "commitment_id": self.commitment_id,
             "kernel_name": self.kernel_name,
             "content_hash": self.content_hash,
-            "flagged_for_icm": self.decision == EndorsementDecision.APPROVED and self.conflict_id != "none",
+            "flagged_for_icm": self.decision in (
+                EndorsementDecision.APPROVED, EndorsementDecision.STAGED
+            ) and self.conflict_id != "none",
         }
+        if self.is_staged:
+            meta.update({
+                "cooldown_duration_s": self.cooldown_duration_s,
+                "cooldown_until": self.cooldown_until,
+                "probe_available": self.probe_available,
+            })
+        return meta
+
+
+# ── Cooldown Duration Calculator ─────────────────────────────────────────────────
+
+class CooldownCalculator:
+    """
+    Calculates the appropriate cooldown duration for a staged kernel update.
+
+    Duration formula:
+        duration = min(base + no_probe_penalty + traffic_adjustment, max_duration)
+
+    Where:
+        - base           : Starting cooldown length (default: 5 min)
+        - no_probe_penalty: Added when no domain probes exist for this kernel/template
+        - traffic_adjustment: Added based on requests-per-minute observed in the
+                               Provenance Log (busier system → longer observation)
+        - max_duration   : Hard cap (default: 10 min)
+    """
+
+    DEFAULT_BASE_SECONDS        = 300    # 5 minutes
+    DEFAULT_MAX_SECONDS         = 600    # 10 minutes
+    DEFAULT_NO_PROBE_PENALTY_S  = 120    # 2 minutes penalty for missing probes
+    TRAFFIC_BUCKET_SECONDS      = 60     # Window for measuring request rate (1 min)
+    TRAFFIC_THRESHOLD_PER_MIN   = 10     # Requests/min above which we add time
+    TRAFFIC_PENALTY_SECONDS     = 60     # Extra second-tier added per threshold breach
+
+    def __init__(
+        self,
+        base_seconds: int = DEFAULT_BASE_SECONDS,
+        max_seconds: int = DEFAULT_MAX_SECONDS,
+        no_probe_penalty_s: int = DEFAULT_NO_PROBE_PENALTY_S,
+    ) -> None:
+        self._base = base_seconds
+        self._max = max_seconds
+        self._no_probe_penalty = no_probe_penalty_s
+
+    def calculate(
+        self,
+        probe_available: bool,
+        provenance_log: Any | None,
+        kernel_name: str,
+        template: str,
+    ) -> int:
+        """
+        Returns the cooldown duration in seconds.
+
+        Args:
+            probe_available:  Whether ICM probes exist for this kernel/template.
+            provenance_log:   ProvenanceLog instance (for traffic estimation).
+            kernel_name:      Kernel name (used for traffic lookup).
+            template:         Template name (used for traffic lookup).
+
+        Returns:
+            int: Cooldown duration in seconds.
+        """
+        duration = self._base
+        penalty_reasons: list[str] = []
+
+        # Penalty 1: No domain probes available
+        if not probe_available:
+            duration += self._no_probe_penalty
+            penalty_reasons.append(
+                f"No domain probes found (+{self._no_probe_penalty}s)"
+            )
+
+        # Penalty 2: Traffic volume adjustment
+        if provenance_log:
+            rpm = self._estimate_rpm(provenance_log, kernel_name, template)
+            if rpm >= self.TRAFFIC_THRESHOLD_PER_MIN:
+                # Each full multiple of the threshold adds one time bucket
+                multiplier = int(rpm / self.TRAFFIC_THRESHOLD_PER_MIN)
+                traffic_penalty = min(multiplier * self.TRAFFIC_PENALTY_SECONDS, 120)
+                duration += traffic_penalty
+                penalty_reasons.append(
+                    f"High traffic ({rpm} req/min, +{traffic_penalty}s)"
+                )
+
+        final = min(duration, self._max)
+        if penalty_reasons:
+            logger.info(
+                f"Cooldown duration adjusted: base={self._base}s → {final}s "
+                f"[{', '.join(penalty_reasons)}]"
+            )
+        else:
+            logger.info(f"Cooldown duration: {final}s (base, no penalties)")
+
+        return final
+
+    def _estimate_rpm(
+        self,
+        provenance_log: Any,
+        kernel_name: str,
+        template: str,
+    ) -> float:
+        """Estimates recent requests-per-minute from the Provenance Log."""
+        try:
+            entries = provenance_log.get_entries(limit=200)
+            cutoff = time.time() - self.TRAFFIC_BUCKET_SECONDS
+            recent = [
+                e for e in entries
+                if e.timestamp >= cutoff
+                and e.metadata.get("kernel") == kernel_name
+                and e.metadata.get("template") == template
+            ]
+            return len(recent)
+        except Exception as e:
+            logger.debug(f"Could not estimate RPM from provenance log: {e}")
+            return 0.0
+
+
+# ── Staged Update Manager ──────────────────────────────────────────────────────────
+
+class StagedUpdateManager:
+    """
+    Tracks pending STAGED endorsements and promotes them to APPROVED
+    after the cooldown period elapses without critical violations.
+
+    Developer Usage:
+        # On each TheseusWrapper.chat() cycle, call:
+        manager.tick(provenance_log)
+        # If the production kernel needs updating:
+        promoted = manager.get_promotable()
+        for record in promoted:
+            kernel.update_commitment(record.commitment_id, record.rule_text)
+
+    Typically owned by TheseusWrapper and wired into the chat() loop.
+    """
+
+    def __init__(self) -> None:
+        self._staged: list[EndorsementRecord] = []
+
+    def register(self, record: EndorsementRecord) -> None:
+        """Registers a STAGED record for tracking."""
+        if record.is_staged:
+            self._staged.append(record)
+            logger.info(
+                f"StagedUpdateManager: registered staged endorsement "
+                f"id={record.id[:8]}... cooldown_until={record.cooldown_until}"
+            )
+
+    def get_active(self) -> list[EndorsementRecord]:
+        """Returns all staged endorsements still in their cooldown window."""
+        return [r for r in self._staged if not r.is_cooldown_expired]
+
+    def get_promotable(self) -> list[EndorsementRecord]:
+        """
+        Returns staged endorsements whose cooldown has expired without
+        being rejected. Removes them from the tracking list.
+        """
+        promotable = [r for r in self._staged if r.is_cooldown_expired]
+        for r in promotable:
+            self._staged.remove(r)
+        return promotable
+
+    def reject_staged(self, record_id: str, reason: str = "") -> bool:
+        """
+        Rejects and removes a staged endorsement (e.g. on CriticalDivergenceError).
+        Returns True if found and removed.
+        """
+        for r in self._staged:
+            if r.id == record_id:
+                self._staged.remove(r)
+                logger.warning(
+                    f"StagedUpdateManager: staged endorsement REJECTED "
+                    f"id={record_id[:8]}... reason={reason!r}"
+                )
+                return True
+        return False
+
+    def has_active_staged(self) -> bool:
+        return len(self.get_active()) > 0
 
 
 # ── Approval Channels ─────────────────────────────────────────────────────────────
@@ -123,7 +328,8 @@ def cli_approval_channel(conflict: ConflictRecord) -> tuple[EndorsementDecision,
     """
     Default CLI approval channel.
     Prompts user for approval in interactive terminal.
-    
+    Includes a 'STAGED' option for supervised cooldown observation.
+
     WARNING: This blocks the current thread. In server environments (FastAPI/Flask),
     always use a custom non-blocking callback.
     """
@@ -136,24 +342,31 @@ def cli_approval_channel(conflict: ConflictRecord) -> tuple[EndorsementDecision,
         return EndorsementDecision.PENDING, "system", "Awaiting external approval (non-TTY)"
 
     print(conflict.summary())
-    print("\nDo you want to override this rule conflict?")
-    print("  [y] Yes — approve and sign override")
+    print("\nHow do you want to handle this rule conflict?")
+    print("  [y] Yes — approve and apply kernel update immediately")
+    print("  [s] Stage — approve with cooldown (sandbox observation period)")
     print("  [n] No — cancel, keep existing rule")
 
     while True:
         try:
-            choice = input("\nYour decision (y/n): ").strip().lower()
+            choice = input("\nYour decision (y/s/n): ").strip().lower()
             if choice in ("y", "yes"):
                 operator_id = input("Operator ID (name/email): ").strip() or "anonymous"
                 rationale = input("Override rationale: ").strip() or "Manual approval"
                 return EndorsementDecision.APPROVED, operator_id, rationale
+            elif choice in ("s", "stage", "staged"):
+                operator_id = input("Operator ID (name/email): ").strip() or "anonymous"
+                rationale = input("Staged approval rationale: ").strip() or "Staged manual approval"
+                return EndorsementDecision.STAGED, operator_id, rationale
             elif choice in ("n", "no"):
                 return EndorsementDecision.REJECTED, "system", "User rejected"
             else:
-                print("Invalid input. Type 'y' or 'n'.")
+                print("Invalid input. Type 'y', 's', or 'n'.")
         except EOFError:
             # Handle cases where input() is called but stdin is closed
             return EndorsementDecision.PENDING, "system", "Stdin closed while awaiting input"
+    # Unreachable — satisfies static analysers that don't track while-True exhaustion
+    return EndorsementDecision.PENDING, "system", "Unexpected exit from approval loop"
 
 
 def auto_approve_channel(
@@ -173,6 +386,24 @@ def auto_approve_channel(
     return _channel
 
 
+def auto_staged_channel(
+    operator_id: str = "auto",
+    rationale: str = "Auto staged approval",
+) -> ApprovalCallback:
+    """
+    Auto staged approval channel for test and CI environments.
+    Returns STAGED decision, which will trigger cooldown logic.
+    Do not use in production.
+    """
+    def _channel(conflict: ConflictRecord) -> tuple[EndorsementDecision, str, str]:
+        logger.warning(
+            f"AUTO-STAGED active: Override of '{conflict.rule_text}' staged. "
+            "This channel should only be used in test environments."
+        )
+        return EndorsementDecision.STAGED, operator_id, rationale
+    return _channel
+
+
 def auto_reject_channel() -> ApprovalCallback:
     """Auto reject channel for test environments."""
     def _channel(conflict: ConflictRecord) -> tuple[EndorsementDecision, str, str]:
@@ -206,10 +437,22 @@ class ReflectiveEndorsement:
         kernel: Any,                          # ConstitutionalKernel
         provenance_log: Any,                  # ProvenanceLog
         approval_channel: ApprovalCallback | None = None,
+        staged_manager: StagedUpdateManager | None = None,
+        cooldown_base_s: int = CooldownCalculator.DEFAULT_BASE_SECONDS,
+        cooldown_max_s: int = CooldownCalculator.DEFAULT_MAX_SECONDS,
+        no_probe_penalty_s: int = CooldownCalculator.DEFAULT_NO_PROBE_PENALTY_S,
+        template: str = "general",
     ) -> None:
         self._kernel = kernel
         self._log = provenance_log
         self._approval_channel = approval_channel or cli_approval_channel
+        self._staged_manager = staged_manager or StagedUpdateManager()
+        self._cooldown_calc = CooldownCalculator(
+            base_seconds=cooldown_base_s,
+            max_seconds=cooldown_max_s,
+            no_probe_penalty_s=no_probe_penalty_s,
+        )
+        self._template = template
         self._pending_records: list[EndorsementRecord] = []
         self._pre_update_snapshot: dict[str, Any] | None = None
 
@@ -228,7 +471,7 @@ class ReflectiveEndorsement:
         - Plastic conflict → RE flow starts, user approval requested
         - No conflict → rule is applied directly, written to log
 
-        Returns: EndorsementRecord (APPROVED or REJECTED)
+        Returns: EndorsementRecord (APPROVED, STAGED, or REJECTED)
         Raises:  AxiomaticViolationError — on axiomatic violation
         """
         try:
@@ -258,7 +501,7 @@ class ReflectiveEndorsement:
         operator_id: str,
         commitment_new_value: Any,
     ) -> EndorsementRecord:
-        """Three stages of RE flow: Conflict record → Approval → Application."""
+        """Four stages of RE flow: Conflict record → Approval → Application → Log."""
 
         # Stage 1: Create ConflictRecord
         conflict = ConflictRecord(
@@ -275,6 +518,10 @@ class ReflectiveEndorsement:
         decision, actual_operator_id, rationale = self._approval_channel(conflict)
 
         # Stage 3: Apply decision
+        probe_available = self._check_probe_availability()
+        cooldown_duration_s: int | None = None
+        cooldown_until: float | None = None
+
         if decision == EndorsementDecision.APPROVED:
             applied = self._apply_override(
                 commitment_id=conflict.conflicting_commitment_id,
@@ -295,6 +542,24 @@ class ReflectiveEndorsement:
                     f"commitment={conflict.conflicting_commitment_id} | "
                     f"operator={actual_operator_id or operator_id}"
                 )
+
+        elif decision == EndorsementDecision.STAGED:
+            # Calculate cooldown duration — applies penalties as needed
+            cooldown_duration_s = self._cooldown_calc.calculate(
+                probe_available=probe_available,
+                provenance_log=self._log,
+                kernel_name=self._kernel.name,
+                template=self._template,
+            )
+            cooldown_until = time.time() + cooldown_duration_s
+            logger.info(
+                f"Override STAGED | "
+                f"commitment={conflict.conflicting_commitment_id} | "
+                f"cooldown={cooldown_duration_s}s | "
+                f"probe_available={probe_available} | "
+                f"operator={actual_operator_id or operator_id}"
+            )
+
         else:
             logger.info(
                 f"Override rejected | "
@@ -313,12 +578,19 @@ class ReflectiveEndorsement:
             operator_id=actual_operator_id or operator_id,
             rationale=rationale,
             kernel_name=self._kernel.name,
+            cooldown_duration_s=cooldown_duration_s,
+            cooldown_until=cooldown_until,
+            probe_available=probe_available,
         )
 
         # Write to log in either case
         self._write_to_log(record)
         self._pending_records.append(record)
 
+        # Register with staged manager if STAGED
+        if record.is_staged:
+            self._staged_manager.register(record)
+
         return record
 
     # ── Helper Methods ──────────────────────────────────────────────────────
@@ -343,6 +615,21 @@ class ReflectiveEndorsement:
             )
             return False
 
+    def _check_probe_availability(self) -> bool:
+        """
+        Checks whether ICM probes exist for the current kernel/template combination.
+        Returns True if probes are available, False otherwise.
+        """
+        try:
+            from ct_toolkit.divergence.l3_icm import ICMRunner
+            return ICMRunner.has_probes(
+                template=self._template,
+                kernel_name=self._kernel.name,
+            )
+        except Exception as e:
+            logger.debug(f"Probe availability check failed: {e}. Assuming unavailable.")
+            return False
+
     def _write_to_log(self, record: EndorsementRecord) -> None:
         """Writes the endorsement record to the Provenance Log."""
         try:
@@ -373,12 +660,16 @@ class ReflectiveEndorsement:
             kernel_name=self._kernel.name,
         )
 
-    # ── Querying ─────────────────────────────────────────────────────────────
+    # ── Public Properties / Accessors ──────────────────────────────────────────
+
+    @property
+    def staged_manager(self) -> StagedUpdateManager:
+        return self._staged_manager
 
     def get_pending_records(self) -> list[EndorsementRecord]:
         """Overrides approved in this session requiring ICM monitoring."""
         return [r for r in self._pending_records
-                if r.decision == EndorsementDecision.APPROVED
+                if r.decision in (EndorsementDecision.APPROVED, EndorsementDecision.STAGED)
                 and r.conflict_id != "none"]
 
     def has_active_overrides(self) -> bool:

{ct_toolkit-0.3.7 → ct_toolkit-0.3.8}/ct_toolkit.egg-info/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: ct-toolkit
-Version: 0.3.7
+Version: 0.3.8
 Summary: Computational Theseus Toolkit — Identity Continuity Guardrails for Agentic Systems
 Author: Hakan Damar
 License: Apache-2.0

{ct_toolkit-0.3.7 → ct_toolkit-0.3.8}/pyproject.toml

@@ -4,7 +4,7 @@ build-backend = "setuptools.build_meta"
 
 [project]
 name = "ct-toolkit"
-version = "0.3.7"
+version = "0.3.8"
 description = "Computational Theseus Toolkit — Identity Continuity Guardrails for Agentic Systems"
 readme = "README.md"
 requires-python = ">=3.11"