devtorch-core 3.0.1__py3-none-any.whl

devtorch_core/session/simulator.py

@@ -0,0 +1,132 @@
+"""What-if simulation for multi-agent sessions."""
+
+from __future__ import annotations
+
+import copy
+import dataclasses
+import datetime as _dt
+import json
+import uuid
+from pathlib import Path
+from typing import Any, Dict, List, Optional
+
+from .models import Session, Subtask
+from .orchestrator import SessionOrchestrator
+
+
+@dataclasses.dataclass
+class SimulationResult:
+    """Result of a single what-if simulation run."""
+
+    simulation_id: str
+    session_id: str
+    baseline_assumptions: Dict[str, Any]
+    alternate_assumptions: Dict[str, Any]
+    predicted_outcome: str
+    affected_concepts: List[str]
+    created_at: str
+
+    def to_dict(self) -> dict:
+        return dataclasses.asdict(self)
+
+
+class WhatIfSimulator:
+    """
+    Run what-if simulations against a Session without mutating the original.
+
+    A subtask is considered affected when an alternate assumption key matches:
+    - the subtask concept, or
+    - a word inside the subtask description, or
+    - a key in the subtask's own assumptions.
+    """
+
+    def __init__(self, gcc_dir: Path) -> None:
+        self._orchestrator = SessionOrchestrator(gcc_dir)
+
+    def simulate(
+        self,
+        session_id: str,
+        alternate_assumptions: Dict[str, Any],
+    ) -> SimulationResult:
+        """
+        Load *session_id*, copy its subtasks, apply *alternate_assumptions*,
+        determine which subtasks are affected, and return a SimulationResult.
+
+        The original session on disk is never modified.
+        """
+        try:
+            session = self._orchestrator.get_session(session_id)
+        except FileNotFoundError as exc:
+            raise ValueError(str(exc)) from exc
+
+        baseline = dict(session.assumptions)
+        affected_concepts = self._affected_concepts(session, alternate_assumptions)
+        outcome = self.predict_outcome(session, alternate_assumptions)
+
+        return SimulationResult(
+            simulation_id=str(uuid.uuid4()),
+            session_id=session_id,
+            baseline_assumptions=baseline,
+            alternate_assumptions=dict(alternate_assumptions),
+            predicted_outcome=outcome,
+            affected_concepts=sorted(set(affected_concepts)),
+            created_at=_dt.datetime.now(tz=_dt.timezone.utc).isoformat(),
+        )
+
+    def predict_outcome(
+        self,
+        session: Session,
+        alternate_assumptions: Dict[str, Any],
+    ) -> str:
+        """Return a concise human-readable summary of predicted changes."""
+        affected = self._affected_concepts(session, alternate_assumptions)
+        if not affected:
+            return (
+                "No subtasks are affected by the alternate assumptions; "
+                "predicted outcome unchanged."
+            )
+
+        lines = [
+            f"Alternate assumptions change {len(affected)} concept(s): "
+            + ", ".join(sorted(set(affected)))
+        ]
+        for subtask in session.subtasks:
+            if subtask.concept in affected:
+                old = session.assumptions.get(subtask.concept)
+                new = alternate_assumptions.get(subtask.concept)
+                lines.append(
+                    f"- Subtask '{subtask.subtask_id}' ({subtask.concept}): "
+                    f"assumption shifts from {old!r} to {new!r}."
+                )
+        return "\n".join(lines)
+
+    @staticmethod
+    def _affected_concepts(
+        session: Session,
+        alternate_assumptions: Dict[str, Any],
+    ) -> List[str]:
+        """Return concepts that would be affected by alternate assumptions."""
+        affected: List[str] = []
+        alt_keys = set(alternate_assumptions.keys())
+        for subtask in session.subtasks:
+            if subtask.concept in alt_keys:
+                affected.append(subtask.concept)
+                continue
+            for key in alt_keys:
+                if key in subtask.description.split():
+                    affected.append(subtask.concept)
+                    break
+                if key in subtask.assumptions:
+                    affected.append(subtask.concept)
+                    break
+        return affected
+
+    @staticmethod
+    def _apply_assumptions_to_subtasks(
+        session: Session,
+        alternate_assumptions: Dict[str, Any],
+    ) -> Session:
+        """Return a copy of *session* with alternate assumptions applied."""
+        cloned = copy.deepcopy(session)
+        cloned.assumptions = {**cloned.assumptions, **alternate_assumptions}
+        return cloned

devtorch_core/signing.py

@@ -0,0 +1,290 @@
+"""
+Sprint 9 — Optional cryptographic signing of the `.GCC/events.log.jsonl` hash chain.
+
+Provides HMAC-SHA256 event signatures behind a feature flag. When enabled, every
+appended event carries a ``signature`` field that proves the event was produced by
+a party holding the repository signing key. The prior_hash chain remains intact and
+continues to be verified by ``devtorch doctor``.
+
+Design decisions
+----------------
+* HMAC-SHA256 is used so signing works with zero external dependencies (the OSS
+  core has no ``cryptography`` requirement).
+* The signing key is a 32-byte random value stored in ``.GCC/signing.key``.
+* Enabling signing is idempotent: if a key already exists it is reused.
+* Verification is tolerant: if a line lacks a signature, it is reported but does not
+  break the chain unless signing is explicitly enabled.
+* Feature flag: ``DEVTORCH_SIGN_LOG=1`` environment variable, or a
+  ``.GCC/signing.json`` config with ``enabled: true``.
+"""
+
+from __future__ import annotations
+
+import base64
+import dataclasses
+import hashlib
+import hmac
+import json
+import os
+import secrets
+from pathlib import Path
+from typing import Dict, List, Optional
+
+
+SIGNING_KEY_FILE = "signing.key"
+SIGNING_CONFIG_FILE = "signing.json"
+SIGNATURE_ALGORITHM = "hmac-sha256"
+SIGNATURE_ENV = "DEVTORCH_SIGN_LOG"
+
+
+@dataclasses.dataclass
+class SigningConfig:
+    """Resolved signing configuration for a repository."""
+
+    enabled: bool
+    key_path: Optional[str] = None
+    algorithm: str = SIGNATURE_ALGORITHM
+
+    @property
+    def key_file(self) -> Optional[Path]:
+        if self.key_path is None:
+            return None
+        return Path(self.key_path)
+
+
+class SigningError(RuntimeError):
+    """Raised when signing or verification cannot proceed."""
+
+
+# ---------------------------------------------------------------------------
+# Configuration
+# ---------------------------------------------------------------------------
+
+
+def _gcc_dir_from_cwd() -> Path:
+    """Best-effort current repo .GCC directory."""
+    return Path.cwd() / ".GCC"
+
+
+def _read_signing_config(gcc_dir: Path) -> SigningConfig:
+    """Resolve signing config from environment + config file."""
+    env_enabled = os.environ.get(SIGNATURE_ENV, "").strip().lower() in (
+        "1",
+        "true",
+        "yes",
+    )
+
+    config_path = gcc_dir / SIGNING_CONFIG_FILE
+    file_enabled = False
+    if config_path.exists():
+        try:
+            data = json.loads(config_path.read_text(encoding="utf-8"))
+            file_enabled = bool(data.get("enabled"))
+        except (json.JSONDecodeError, OSError):
+            file_enabled = False
+
+    enabled = env_enabled or file_enabled
+    return SigningConfig(
+        enabled=enabled,
+        key_path=str(gcc_dir / SIGNING_KEY_FILE),
+        algorithm=SIGNATURE_ALGORITHM,
+    )
+
+
+def _write_signing_config(gcc_dir: Path, enabled: bool) -> None:
+    """Persist signing config in .GCC/signing.json."""
+    config_path = gcc_dir / SIGNING_CONFIG_FILE
+    data = {"enabled": enabled, "algorithm": SIGNATURE_ALGORITHM}
+    config_path.write_text(json.dumps(data, indent=2), encoding="utf-8")
+
+
+# ---------------------------------------------------------------------------
+# Key management
+# ---------------------------------------------------------------------------
+
+
+def _generate_key() -> bytes:
+    """Generate a new 32-byte random signing key."""
+    return secrets.token_bytes(32)
+
+
+def _load_key(key_path: Path) -> Optional[bytes]:
+    """Load a base64-encoded signing key from disk."""
+    if not key_path.exists():
+        return None
+    try:
+        raw = key_path.read_bytes()
+        return base64.b64decode(raw.strip())
+    except (OSError, ValueError):
+        return None
+
+
+def _save_key(key_path: Path, key: bytes) -> None:
+    """Persist a signing key with restrictive permissions."""
+    encoded = base64.b64encode(key)
+    key_path.write_bytes(encoded)
+    try:
+        # Restrict to owner read/write (0o600) on Unix
+        key_path.chmod(0o600)
+    except (OSError, NotImplementedError):
+        pass
+
+
+def get_or_create_key(gcc_dir: Path) -> bytes:
+    """Load existing key or generate and save one."""
+    key_path = gcc_dir / SIGNING_KEY_FILE
+    key = _load_key(key_path)
+    if key is not None:
+        return key
+    key = _generate_key()
+    _save_key(key_path, key)
+    return key
+
+
+# ---------------------------------------------------------------------------
+# Signing
+# ---------------------------------------------------------------------------
+
+
+def _canonical_event_bytes(event: dict) -> bytes:
+    """Canonical JSON encoding of the event minus signature and hash fields."""
+    canonical = {k: v for k, v in event.items() if k not in ("signature", "hash")}
+    return json.dumps(canonical, sort_keys=True).encode("utf-8")
+
+
+def sign_event(event: dict, key: bytes) -> dict:
+    """Return a new event dict with ``signature`` populated."""
+    payload = _canonical_event_bytes(event)
+    sig = hmac.new(key, payload, hashlib.sha256).hexdigest()
+    signed = dict(event)
+    signed["signature"] = f"{SIGNATURE_ALGORITHM}={sig}"
+    return signed
+
+
+def verify_event(event: dict, key: bytes) -> bool:
+    """Verify the signature on an event. Returns False if missing/invalid."""
+    sig_field = event.get("signature")
+    if not sig_field or not isinstance(sig_field, str):
+        return False
+    if "=" not in sig_field:
+        return False
+    algo, _, value = sig_field.partition("=")
+    if algo != SIGNATURE_ALGORITHM:
+        return False
+    expected = hmac.new(key, _canonical_event_bytes(event), hashlib.sha256).hexdigest()
+    return hmac.compare_digest(expected, value)
+
+
+# ---------------------------------------------------------------------------
+# High-level helpers
+# ---------------------------------------------------------------------------
+
+
+def signing_enabled(gcc_dir: Path) -> bool:
+    """Return True if signing is enabled for this repository."""
+    return _read_signing_config(gcc_dir).enabled
+
+
+def enable_signing(gcc_dir: Path) -> bytes:
+    """Enable signing for the repository, creating a key if needed."""
+    key = get_or_create_key(gcc_dir)
+    _write_signing_config(gcc_dir, enabled=True)
+    return key
+
+
+def disable_signing(gcc_dir: Path) -> None:
+    """Disable signing for the repository (does not delete the key)."""
+    _write_signing_config(gcc_dir, enabled=False)
+
+
+def sign_line_if_enabled(line: dict, gcc_dir: Path) -> dict:
+    """Sign a single event dict if signing is enabled and a key exists."""
+    config = _read_signing_config(gcc_dir)
+    if not config.enabled or config.key_file is None:
+        return line
+    key = get_or_create_key(gcc_dir)
+    return sign_event(line, key)
+
+
+# ---------------------------------------------------------------------------
+# Batch verification
+# ---------------------------------------------------------------------------
+
+
+def verify_log(gcc_dir: Path) -> List[dict]:
+    """
+    Verify all signatures in events.log.jsonl.
+
+    Returns a list of failure records:
+        {line_no, event_hash, reason}
+
+    Behaviour:
+    * If signing is not enabled and no signatures exist, returns an empty list.
+    * Only lines from the first signed line onward are checked. This allows a
+      smooth transition: events created before signing was enabled remain
+      unsigned, but once signing is enabled every subsequent line must be valid.
+    """
+    log_path = gcc_dir / "events.log.jsonl"
+    config = _read_signing_config(gcc_dir)
+    key: Optional[bytes] = None
+    if config.enabled and config.key_file is not None:
+        key = _load_key(config.key_file)
+
+    failures: List[dict] = []
+    if not log_path.exists():
+        return failures
+
+    text = log_path.read_text(encoding="utf-8")
+    lines = [line.strip() for line in text.splitlines() if line.strip()]
+    if not lines:
+        return failures
+
+    # Determine the first signed line; earlier lines are pre-signing history.
+    first_signed_index: Optional[int] = None
+    for idx, line in enumerate(lines):
+        try:
+            event = json.loads(line)
+        except json.JSONDecodeError:
+            continue
+        if event.get("signature"):
+            first_signed_index = idx
+            break
+
+    if first_signed_index is None:
+        # No signatures in the log at all.
+        return failures
+
+    for idx in range(first_signed_index, len(lines)):
+        line = lines[idx]
+        line_no = idx + 1
+        try:
+            event = json.loads(line)
+        except json.JSONDecodeError:
+            failures.append({"line_no": line_no, "event_hash": None, "reason": "invalid JSON"})
+            continue
+
+        has_signature = bool(event.get("signature"))
+        if not has_signature:
+            failures.append({
+                "line_no": line_no,
+                "event_hash": event.get("hash"),
+                "reason": "missing signature while signing enabled",
+            })
+            continue
+
+        if key is None:
+            failures.append({
+                "line_no": line_no,
+                "event_hash": event.get("hash"),
+                "reason": "signature present but signing key not available",
+            })
+            continue
+
+        if not verify_event(event, key):
+            failures.append({
+                "line_no": line_no,
+                "event_hash": event.get("hash"),
+                "reason": "invalid signature",
+            })
+
+    return failures

devtorch_core/sis.py

@@ -0,0 +1,197 @@
+"""
+Sprint 5 – SIS (Sensitivity Inference Safety) A3: corpus format, evaluation harness, quarantine decision tree.
+
+SIS-TC: Test corpus format (prompt, label_safe), loader, ROC/FPR/FNR evaluation.
+Quarantine: deterministic decision tree (drop, log, rep_penalty, abstain, exclude after 3 consecutive).
+"""
+
+from __future__ import annotations
+
+import json
+from dataclasses import dataclass, field
+from pathlib import Path
+from typing import Callable, List, Optional
+
+SIS_TC_CORPUS_NAME = "sis_tc_corpus.jsonl"
+SIS_TC_REPORT_NAME = "sis_tc_report.json"
+SIS_QUARANTINE_LOG_NAME = "quarantine_events.jsonl"
+SIS_DIR_NAME = "sis"
+QUARANTINE_EVENT_TYPE = "QUARANTINE"
+
+# Decision outcomes
+OUTCOME_DROP = "drop"
+OUTCOME_LOG = "log"
+OUTCOME_REP_PENALTY = "rep_penalty"
+OUTCOME_ABSTAIN = "abstain"  # insufficient valid peers
+OUTCOME_EXCLUDE = "exclude"  # 3 consecutive quarantines for same agent
+
+
+@dataclass
+class SISTCCorpusEntry:
+    """Single SIS-TC corpus entry."""
+    prompt_id: str
+    prompt_text: str
+    label_safe: bool  # True = safe, False = unsafe
+    metadata: Optional[dict] = None
+
+    def to_dict(self) -> dict:
+        d = {"prompt_id": self.prompt_id, "prompt_text": self.prompt_text, "label_safe": self.label_safe}
+        if self.metadata:
+            d["metadata"] = self.metadata
+        return d
+
+    @classmethod
+    def from_dict(cls, d: dict) -> "SISTCCorpusEntry":
+        return cls(
+            prompt_id=str(d["prompt_id"]),
+            prompt_text=str(d["prompt_text"]),
+            label_safe=bool(d["label_safe"]),
+            metadata=d.get("metadata"),
+        )
+
+
+def load_sis_tc_corpus(path: Path) -> List[SISTCCorpusEntry]:
+    """Load SIS-TC corpus from JSONL (one JSON object per line)."""
+    if not path.exists():
+        return []
+    entries = []
+    with path.open("r", encoding="utf-8") as f:
+        for line in f:
+            line = line.strip()
+            if not line:
+                continue
+            try:
+                entries.append(SISTCCorpusEntry.from_dict(json.loads(line)))
+            except (json.JSONDecodeError, KeyError):
+                continue
+    return entries
+
+
+@dataclass
+class SISTCReport:
+    """SIS-TC evaluation report: counts, FPR, FNR, chosen threshold."""
+    n_total: int
+    n_safe: int
+    n_unsafe: int
+    tp: int
+    tn: int
+    fp: int
+    fn: int
+    fpr: float
+    fnr: float
+    threshold_used: float
+    operating_point: Optional[dict] = None  # e.g. {"fpr_target": 0.01, "fnr_target": 0.05}
+
+    def to_dict(self) -> dict:
+        return {
+            "n_total": self.n_total,
+            "n_safe": self.n_safe,
+            "n_unsafe": self.n_unsafe,
+            "tp": self.tp, "tn": self.tn, "fp": self.fp, "fn": self.fn,
+            "fpr": self.fpr, "fnr": self.fnr,
+            "threshold_used": self.threshold_used,
+            "operating_point": self.operating_point,
+        }
+
+
+def run_sis_tc_eval(
+    corpus: List[SISTCCorpusEntry],
+    classifier_fn: Optional[Callable[[str], float]] = None,
+    threshold: float = 0.5,
+) -> SISTCReport:
+    """
+    Run SIS-TC evaluation. classifier_fn(prompt_text) -> float score in [0,1] (higher = safer).
+    If classifier_fn is None, use placeholder: label_safe -> 1.0, else 0.0 (perfect prediction).
+    """
+    n_safe = sum(1 for e in corpus if e.label_safe)
+    n_unsafe = len(corpus) - n_safe
+    if classifier_fn is None:
+        scores = [1.0 if e.label_safe else 0.0 for e in corpus]  # placeholder: perfect prediction
+    else:
+        scores = [classifier_fn(e.prompt_text) for e in corpus]
+    tp = tn = fp = fn = 0
+    for e, s in zip(corpus, scores):
+        pred_safe = s >= threshold
+        if e.label_safe and pred_safe:
+            tp += 1
+        elif e.label_safe and not pred_safe:
+            fn += 1
+        elif not e.label_safe and pred_safe:
+            fp += 1
+        else:
+            tn += 1
+    fpr = fp / (fp + tn) if (fp + tn) > 0 else 0.0
+    fnr = fn / (fn + tp) if (fn + tp) > 0 else 0.0
+    return SISTCReport(
+        n_total=len(corpus),
+        n_safe=n_safe,
+        n_unsafe=n_unsafe,
+        tp=tp, tn=tn, fp=fp, fn=fn,
+        fpr=fpr, fnr=fnr,
+        threshold_used=threshold,
+    )
+
+
+@dataclass
+class QuarantineDecision:
+    """Result of quarantine decision tree."""
+    outcome: str  # drop, log, rep_penalty, abstain, exclude
+    reason: str
+    agent_id: Optional[str] = None
+    consecutive_count: Optional[int] = None
+
+
+def quarantine_decision_tree(
+    agent_id: str,
+    payload_quarantined: bool,
+    valid_peer_count: int,
+    min_peers_required: int,
+    agent_consecutive_quarantines: int,
+    exclude_after_n_consecutive: int = 3,
+) -> QuarantineDecision:
+    """
+    Deterministic SIS quarantine decision tree.
+    - If insufficient valid peers -> abstain.
+    - If agent has >= exclude_after_n_consecutive consecutive quarantines -> exclude.
+    - Else if payload quarantined -> rep_penalty (and log). Otherwise no quarantine (drop = do not forward; log = log only).
+    """
+    if valid_peer_count < min_peers_required:
+        return QuarantineDecision(OUTCOME_ABSTAIN, "Insufficient valid peers", agent_id=agent_id)
+    if agent_consecutive_quarantines >= exclude_after_n_consecutive:
+        return QuarantineDecision(
+            OUTCOME_EXCLUDE,
+            f"Agent {agent_id} exceeded {exclude_after_n_consecutive} consecutive quarantines",
+            agent_id=agent_id,
+            consecutive_count=agent_consecutive_quarantines,
+        )
+    if payload_quarantined:
+        return QuarantineDecision(
+            OUTCOME_REP_PENALTY,
+            "Payload quarantined by classifier",
+            agent_id=agent_id,
+        )
+    return QuarantineDecision(OUTCOME_LOG, "Logged only", agent_id=agent_id)
+
+
+class QuarantineEventStore:
+    """Persist QUARANTINE events for audit (append-only JSONL)."""
+    def __init__(self, gcc_dir: Path) -> None:
+        self.sis_dir = gcc_dir / SIS_DIR_NAME
+        self.log_path = self.sis_dir / SIS_QUARANTINE_LOG_NAME
+
+    def ensure_dir(self) -> None:
+        self.sis_dir.mkdir(parents=True, exist_ok=True)
+
+    def append(self, decision: QuarantineDecision, timestamp: str, round_id: Optional[int] = None) -> None:
+        record = {
+            "event_type": QUARANTINE_EVENT_TYPE,
+            "timestamp": timestamp,
+            "outcome": decision.outcome,
+            "reason": decision.reason,
+            "agent_id": decision.agent_id,
+            "consecutive_count": decision.consecutive_count,
+            "round_id": round_id,
+        }
+        self.ensure_dir()
+        with self.log_path.open("a", encoding="utf-8") as f:
+            f.write(json.dumps(record, sort_keys=True) + "\n")