devtorch-core 3.0.1__py3-none-any.whl

devtorch_core/gcc.py

@@ -0,0 +1,1246 @@
+from __future__ import annotations
+
+import dataclasses
+import datetime as _dt
+import hashlib
+import json
+from pathlib import Path
+from typing import TYPE_CHECKING, Dict, List, Optional, Tuple
+
+from devtorch_core.storage import LocalFileBackend, StorageBackend
+from devtorch_core.signing import sign_line_if_enabled, verify_log, signing_enabled
+
+if TYPE_CHECKING:
+    from .capability import OmegaCapability
+    from .sensitivity import SensitivityEvent
+
+
+GCC_DIR_NAME = ".GCC"
+GCC_VERSION = "gcc-v0"
+EVENT_LOG_NAME = "events.log.jsonl"
+VERSION_FILE_NAME = "VERSION"
+MAIN_MD_NAME = "main.md"
+LOG_MD_NAME = "log.md"
+CAPABILITIES_DIR_NAME = "capabilities"
+OMEGA_FILE_NAME = "omega.json"
+
+# Sprint 1 layout additions
+REFS_DIR_NAME = "refs"
+BRANCHES_DIR_NAME = "branches"
+HEAD_FILE_NAME = "HEAD"
+COMMITS_DIR_NAME = "commits"
+COMMIT_INDEX_FILE_NAME = "COMMIT_INDEX"
+
+# Sprint 2 layout additions
+CONTEXT_DIR_NAME = "context_bundles"
+NODE_STATE_FILE_NAME = "NODE_STATE"
+
+# Sprint 3 layout additions
+SENSITIVITIES_DIR_NAME = "sensitivities"
+PST_REPORTS_DIR_NAME = "pst_reports"
+
+# Sprint 4 layout additions
+CONCEPTS_DIR_NAME = "concepts"
+CONSENSUS_LOCK_FILE = "consensus_lock.json"
+
+# Sprint 5 layout additions
+REP_DIR_NAME = "rep"
+SIS_DIR_NAME = "sis"
+PROMPTS_DIR_NAME = "prompts"
+DELTAF_DIR_NAME = "deltaf"
+RDP_DIR_NAME = "rdp"
+
+
+@dataclasses.dataclass
+class GCCIssue:
+    kind: str
+    message: str
+
+
+class GCCRepository:
+    """
+    Minimal Git-Context-Controller-like store for S0/S1.
+
+    Sprint 0 responsibilities:
+    - Create `.GCC/` layout and version marker.
+    - Maintain append-only JSONL event log with hash chain.
+    - Provide a happy-path `commit` that updates main.md and log.md.
+    - Provide `doctor` to validate layout + basic integrity.
+
+    Sprint 1 additions (branching and merges):
+    - Deterministic commit IDs (no wall-clock dependence).
+    - Branch metadata (`refs/HEAD`, `refs/branches/*`) and commit objects (`commits/*`).
+    - Basic history traversal and fast-forward merges.
+
+    Sprint 2 additions (context retrieval and node state):
+    - Simple node state machine persisted to `.GCC/NODE_STATE`.
+    - MECW-aware context bundles that select a subset of artifacts under a token budget K.
+    - Policy scaffolding for future PROTECTED/PRIVATE redaction (Sprint 5 will enforce it).
+
+    Sprint 3 additions (sensitivity schema, Θ store, Ωᵢ, PST runner):
+    - Structured SensitivityEvent schema with disclosure levels + storage/indexing.
+    - Θ coordination vector updated via pluggable Aggφ on each sensitivity add.
+    - OmegaCapability (v2.1 A1 fields) stored in `.GCC/capabilities/omega.json`.
+    - A1 Textual Mode gate: blocks mode if L̂ > L_max, expired calibration, or PST failed.
+    - PST runner harness (N_pst × N_rep) persists report artifacts in `.GCC/pst_reports/`.
+
+    Sprint 4 additions (invariants I1/I3, variance, consensus lock):
+    - Invariant engine: I1 (commit-backed decisions), I3 (concept handshake). Merge/lock-release gated.
+    - Concept store under `.GCC/concepts/` with hashing for semantic grounding.
+    - Variance calibration and f_max; VARIANCE_ALERT when f_max drops; reputation variance penalty.
+    - Consensus lock/unlock primitives; lock state in `.GCC/consensus_lock.json`.
+
+    Sprint 5 additions (REP, SIS A3, privacy A4):
+    - REP envelope + local transport ledger (record/replay, deterministic checksum).
+    - SIS-TC corpus + evaluation harness (FPR/FNR); quarantine decision tree; QUARANTINE events.
+    - RACP_SYSTEM_PROMPT_v2.1 artifact; Δf estimation + expiry; RDP accountant + PRIVACY_BUDGET_EXHAUSTED.
+    - Disclosure policy: [PRIVATE] suppression, padding, receiver mandate.
+    """
+
+    def __init__(self, root: Path, backend: StorageBackend | None = None) -> None:
+        self.root = root
+        self.gcc_dir = root / GCC_DIR_NAME
+        self._backend: StorageBackend = backend if backend is not None else LocalFileBackend(self.gcc_dir)
+
+    @classmethod
+    def at(cls, root: Path, backend: "StorageBackend | None" = None) -> "GCCRepository":
+        return cls(root, backend=backend)
+
+    def _read(self, *parts: str) -> str:
+        """Read a file key as UTF-8 text. Raises FileNotFoundError if missing."""
+        key = "/".join(parts)
+        return self._backend.read_bytes(key).decode("utf-8")
+
+    def _write(self, *parts: str, content: str) -> None:
+        """Write UTF-8 text to a file key."""
+        key = "/".join(parts)
+        self._backend.write_bytes(key, content.encode("utf-8"))
+
+    def is_initialized(self) -> bool:
+        return self._backend.exists(VERSION_FILE_NAME)
+
+    def init(self) -> None:
+        """Create the initial `.GCC/` layout and stub capability declaration file."""
+        self.gcc_dir.mkdir(parents=True, exist_ok=True)
+
+        # Version marker
+        self._write(VERSION_FILE_NAME, content=f"{GCC_VERSION}\n")
+
+        # Event log (append-only JSONL)
+        if not self._backend.exists(EVENT_LOG_NAME):
+            self._backend.write_bytes(EVENT_LOG_NAME, b"")
+
+        # Roadmap + reasoning log artifacts
+        if not self._backend.exists(MAIN_MD_NAME):
+            self._write(MAIN_MD_NAME, content="# DevTorch reasoning roadmap (main)\n\n")
+        if not self._backend.exists(LOG_MD_NAME):
+            self._write(LOG_MD_NAME, content="# DevTorch reasoning log\n\n")
+
+        # Capabilities stub (Ωᵢ)
+        caps_dir = self.gcc_dir / CAPABILITIES_DIR_NAME
+        caps_dir.mkdir(exist_ok=True)
+        omega_key = f"{CAPABILITIES_DIR_NAME}/{OMEGA_FILE_NAME}"
+        if not self._backend.exists(omega_key):
+            omega_stub = {
+                "version": 0,
+                "schema": "omega-stub-v0",
+                "note": "Capability declaration stub; to be expanded in later sprints.",
+                "created_at": _now_iso(),
+            }
+            self._write(omega_key, content=json.dumps(omega_stub, indent=2, sort_keys=True) + "\n")
+
+        # Sprint 1: refs + commits layout
+        refs_dir = self.gcc_dir / REFS_DIR_NAME
+        branches_dir = refs_dir / BRANCHES_DIR_NAME
+        commits_dir = self.gcc_dir / COMMITS_DIR_NAME
+        context_dir = self.gcc_dir / CONTEXT_DIR_NAME
+        refs_dir.mkdir(exist_ok=True)
+        branches_dir.mkdir(exist_ok=True)
+        commits_dir.mkdir(exist_ok=True)
+        context_dir.mkdir(exist_ok=True)
+
+        head_key = f"{REFS_DIR_NAME}/{HEAD_FILE_NAME}"
+        if not self._backend.exists(head_key):
+            # Default branch is always "main"
+            self._write(head_key, content="main\n")
+
+        main_ref_key = f"{REFS_DIR_NAME}/{BRANCHES_DIR_NAME}/main"
+        if not self._backend.exists(main_ref_key):
+            # Empty main branch (no commits yet)
+            self._write(main_ref_key, content="")
+
+        # Sprint 2: minimal node state
+        if not self._backend.exists(NODE_STATE_FILE_NAME):
+            self._write(
+                NODE_STATE_FILE_NAME,
+                content=json.dumps(
+                    {
+                        "current_branch": "main",
+                        "mode": "idle",  # idle | running | paused
+                        "created_at": _now_iso(),
+                    },
+                    indent=2,
+                    sort_keys=True,
+                )
+                + "\n",
+            )
+
+        # Sprint 3: sensitivities dir + PST reports dir + initial Θ
+        sens_dir = self.gcc_dir / SENSITIVITIES_DIR_NAME
+        pst_dir = self.gcc_dir / PST_REPORTS_DIR_NAME
+        sens_dir.mkdir(exist_ok=True)
+        pst_dir.mkdir(exist_ok=True)
+
+        from .theta import make_theta_store
+        theta_store = make_theta_store(self.gcc_dir)
+        if not theta_store.theta_path.exists():
+            theta_store.save({"version": 1, "updated_at": None, "coordination_vector": {}})
+
+        # Sprint 4: concepts dir + variance dir
+        (self.gcc_dir / CONCEPTS_DIR_NAME).mkdir(exist_ok=True)
+        from .variance import VARIANCE_DIR_NAME
+        (self.gcc_dir / VARIANCE_DIR_NAME).mkdir(exist_ok=True)
+
+        # Sprint 5: rep, sis, prompts, deltaf, rdp
+        (self.gcc_dir / REP_DIR_NAME).mkdir(exist_ok=True)
+        (self.gcc_dir / SIS_DIR_NAME).mkdir(exist_ok=True)
+        (self.gcc_dir / PROMPTS_DIR_NAME).mkdir(exist_ok=True)
+        (self.gcc_dir / DELTAF_DIR_NAME).mkdir(exist_ok=True)
+        (self.gcc_dir / RDP_DIR_NAME).mkdir(exist_ok=True)
+
+        # Sprint 5 — RACP: write default system prompt if not set
+        from .prompt_artifact import DEFAULT_PROMPT_CONTENT as _RACP_DEFAULT
+        if not self.prompt_get():
+            self.prompt_set(_RACP_DEFAULT)
+
+        # Record init event
+        self._append_event(event_type="INIT", payload={"gcc_version": GCC_VERSION})
+
+    def commit(self, message: str = "", agent_id: Optional[str] = None,
+               concepts: Optional[list[str]] = None) -> None:
+        """
+        Sprint-0 commit:
+        - Append a tiny entry to main.md and log.md.
+        - Record a COMMIT event into the JSONL log with hash chain.
+        """
+        if not self.is_initialized():
+            raise RuntimeError("GCC repository is not initialized. Run `devtorch init` first.")
+
+        # Sprint 1: commit metadata and deterministic ID
+        branch = self._current_branch()
+        parent_id = self._read_branch_tip(branch)
+        commit_id = self._next_commit_id()
+
+        ts = _now_iso()
+        _concepts = concepts or []
+        entry_header = f"## Commit at {ts}\n"
+        entry_body = (message or "(no message)") + "\n\n"
+        if _concepts:
+            entry_body = f"**concepts:** {', '.join(_concepts)}\n\n{entry_body}"
+
+        existing_main = self._read(MAIN_MD_NAME) if self._backend.exists(MAIN_MD_NAME) else ""
+        self._write(MAIN_MD_NAME, content=existing_main + entry_header + entry_body)
+
+        existing_log = self._read(LOG_MD_NAME) if self._backend.exists(LOG_MD_NAME) else ""
+        self._write(LOG_MD_NAME, content=existing_log + entry_header + entry_body)
+
+        # Persist commit object
+        commit_obj = {
+            "id": commit_id,
+            "branch": branch,
+            "parent": parent_id,
+            "message": message or "",
+            "timestamp": ts,
+            "concepts": _concepts,
+            "artifacts": {
+                "main": str(MAIN_MD_NAME),
+                "log": str(LOG_MD_NAME),
+                "capabilities": str(Path(CAPABILITIES_DIR_NAME) / OMEGA_FILE_NAME),
+            },
+        }
+        if agent_id is not None:
+            commit_obj["agent_id"] = agent_id
+        self._write(COMMITS_DIR_NAME, f"{commit_id}.json",
+                    content=json.dumps(commit_obj, indent=2, sort_keys=True) + "\n")
+
+        # Update branch tip
+        self._write_branch_tip(branch, commit_id)
+
+        # Record COMMIT event including lineage
+        self._append_event(
+            event_type="COMMIT",
+            payload={
+                "message": message or "",
+                "timestamp": ts,
+                "branch": branch,
+                "commit_id": commit_id,
+                "parent": parent_id,
+                "concepts": _concepts,
+            },
+        )
+
+    # Sprint 1 public API
+
+    def create_branch(self, name: str, from_ref: Optional[str] = None) -> None:
+        """Create a new branch pointing at from_ref (or current tip if omitted)."""
+        if not name:
+            raise ValueError("Branch name must be non-empty.")
+        if "/" in name or name.strip() != name:
+            raise ValueError("Branch name must not contain '/' or surrounding whitespace.")
+
+        branches_dir = self.gcc_dir / REFS_DIR_NAME / BRANCHES_DIR_NAME
+        branches_dir.mkdir(parents=True, exist_ok=True)
+
+        if from_ref is None:
+            from_ref = self._read_branch_tip(self._current_branch())
+
+        (branches_dir / name).write_text(from_ref or "", encoding="utf-8")
+        self._append_event(event_type="BRANCH", payload={"name": name, "from": from_ref})
+
+    def history(self, branch: Optional[str] = None) -> List[dict]:
+        """
+        Return commit history for a branch, newest first.
+        """
+        if branch is None:
+            branch = self._current_branch()
+
+        tip = self._read_branch_tip(branch)
+        commits_dir = self.gcc_dir / COMMITS_DIR_NAME
+        history: List[dict] = []
+
+        while tip:
+            commit_path = commits_dir / f"{tip}.json"
+            if not commit_path.exists():
+                break
+            obj = json.loads(commit_path.read_text(encoding="utf-8"))
+            history.append(obj)
+            tip = obj.get("parent")
+
+        return history
+
+    def merge_fast_forward(self, source: str, target: Optional[str] = None) -> None:
+        """
+        Fast-forward merge: make target branch tip equal to source tip when target is an ancestor.
+        """
+        if target is None:
+            target = self._current_branch()
+
+        branches_dir = self.gcc_dir / REFS_DIR_NAME / BRANCHES_DIR_NAME
+        commits_dir = self.gcc_dir / COMMITS_DIR_NAME
+
+        source_tip = self._read_branch_tip(source)
+        target_tip = self._read_branch_tip(target)
+
+        if not source_tip:
+            raise RuntimeError(f"Source branch `{source}` has no commits to merge.")
+
+        # Sprint 4: I1 (commit-backed) invariant before any merge logic
+        from .invariants import (
+            InvariantContext,
+            InvariantEngine,
+            check_i1_commit_backed,
+            make_i3_semantic_handshake,
+        )
+        from .invariants import ConceptStore as InvariantConceptStore
+        context = InvariantContext(
+            operation="merge",
+            branch_tips={source: source_tip, target: target_tip or ""},
+            concepts_used=[],
+        )
+        engine = InvariantEngine()
+        engine.register("I1", check_i1_commit_backed)
+        concept_store = InvariantConceptStore(self.gcc_dir)
+        engine.register("I3", make_i3_semantic_handshake(concept_store))
+        failures = engine.evaluate(self, context)
+        if failures:
+            raise RuntimeError(
+                f"Invariant check failed: {failures[0].message}. Fix: {failures[0].actionable_fix}"
+            )
+
+        # Walk ancestors of source to see if target_tip is an ancestor (or empty for fast-forward from root).
+        ancestor = source_tip
+        target_is_ancestor = target_tip is None
+        while ancestor and not target_is_ancestor:
+            if ancestor == target_tip:
+                target_is_ancestor = True
+                break
+            commit_path = commits_dir / f"{ancestor}.json"
+            if not commit_path.exists():
+                break
+            obj = json.loads(commit_path.read_text(encoding="utf-8"))
+            ancestor = obj.get("parent")
+
+        if not target_is_ancestor:
+            raise RuntimeError("Non fast-forward merges are not yet supported in Sprint 1.")
+
+        # Update target branch tip
+        (branches_dir / target).write_text(source_tip, encoding="utf-8")
+
+        # Append a small note into main/log to preserve lineage information.
+        main_md = self.gcc_dir / MAIN_MD_NAME
+        log_md = self.gcc_dir / LOG_MD_NAME
+        ts = _now_iso()
+        note = f"### Merge fast-forward `{target}` <- `{source}` at {ts} (tip {source_tip})\n\n"
+        for path in (main_md, log_md):
+            with path.open("a", encoding="utf-8") as f:
+                f.write(note)
+
+        self._append_event(
+            event_type="MERGE",
+            payload={
+                "source": source,
+                "target": target,
+                "new_tip": source_tip,
+                "old_target_tip": target_tip,
+            },
+        )
+
+    # Sprint 4 public API: consensus lock, concepts, variance
+
+    def _lock_path(self) -> Path:
+        return self.gcc_dir / CONSENSUS_LOCK_FILE
+
+    def is_locked(self) -> bool:
+        p = self._lock_path()
+        if not p.exists():
+            return False
+        try:
+            data = json.loads(p.read_text(encoding="utf-8"))
+            return bool(data.get("locked", False))
+        except (json.JSONDecodeError, OSError):
+            return False
+
+    def lock(self, reason: str = "", required_peer_count: Optional[int] = None) -> None:
+        """Acquire consensus lock. Optional required_peer_count can be checked against f_max."""
+        if not self.is_initialized():
+            raise RuntimeError("GCC repository is not initialized. Run `devtorch init` first.")
+        if self.is_locked():
+            raise RuntimeError("Repository is already locked. Run `devtorch unlock` first.")
+        payload: dict = {
+            "locked": True,
+            "reason": reason or "consensus lock",
+            "locked_at": _now_iso(),
+        }
+        if required_peer_count is not None:
+            payload["required_peer_count"] = required_peer_count
+        self._lock_path().write_text(
+            json.dumps(payload, indent=2) + "\n",
+            encoding="utf-8",
+        )
+        self._append_event(event_type="LOCK", payload=payload)
+
+    def unlock(self) -> None:
+        """Release consensus lock. I1 is run so that only commit-backed state can finalize."""
+        if not self.is_initialized():
+            raise RuntimeError("GCC repository is not initialized. Run `devtorch init` first.")
+        if not self.is_locked():
+            return
+        from .invariants import (
+            InvariantContext,
+            InvariantEngine,
+            check_i1_commit_backed,
+        )
+        branch = self._current_branch()
+        tip = self._read_branch_tip(branch)
+        context = InvariantContext(
+            operation="lock_release",
+            branch_tips={branch: tip or ""},
+            concepts_used=[],
+        )
+        engine = InvariantEngine()
+        engine.register("I1", check_i1_commit_backed)
+        failures = engine.evaluate(self, context)
+        if failures:
+            raise RuntimeError(
+                f"Cannot unlock: invariant I1 failed. {failures[0].message}. Fix: {failures[0].actionable_fix}"
+            )
+        payload = {"unlocked_at": _now_iso()}
+        self._lock_path().write_text(
+            json.dumps({"locked": False, **payload}, indent=2) + "\n",
+            encoding="utf-8",
+        )
+        self._append_event(event_type="UNLOCK", payload=payload)
+
+    def concept_add(self, name: str, definition: str) -> None:
+        """Add a concept definition for I3 semantic grounding."""
+        if not self.is_initialized():
+            raise RuntimeError("GCC repository is not initialized. Run `devtorch init` first.")
+        from .invariants import ConceptStore as InvariantConceptStore
+        store = InvariantConceptStore(self.gcc_dir)
+        store.add(name, definition)
+
+    def concept_list(self) -> List[str]:
+        """List registered concept names."""
+        if not self.is_initialized():
+            raise RuntimeError("GCC repository is not initialized. Run `devtorch init` first.")
+        from .invariants import ConceptStore as InvariantConceptStore
+        store = InvariantConceptStore(self.gcc_dir)
+        return store.list_concepts()
+
+    def variance_calibrate(self, agent_variances: Dict[str, float]) -> "VarianceReport":
+        """Run variance calibration and persist report under .GCC/variance/."""
+        if not self.is_initialized():
+            raise RuntimeError("GCC repository is not initialized. Run `devtorch init` first.")
+        from .variance import variance_calibrate as calibrate, VarianceStore, VarianceReport
+        report = calibrate(agent_variances)
+        VarianceStore(self.gcc_dir).save_report(report)
+        return report
+
+    def get_variance_report(self) -> Optional["VarianceReport"]:
+        """Load last variance calibration report if present."""
+        if not self.is_initialized():
+            return None
+        from .variance import VarianceStore, VarianceReport
+        return VarianceStore(self.gcc_dir).load_report()
+
+    def variance_monitor_run(
+        self,
+        agent_variances: Optional[Dict[str, float]] = None,
+    ) -> dict:
+        """
+        Run A2 rolling variance monitoring: compute/live-update f_max, persist live state.
+        Emits VARIANCE_ALERT when f_max drops or f_max_live=0; when f_max_live=0
+        deterministic mode is forced (see variance_deterministic_mode_forced).
+        Returns dict with f_max_live, previous_f_max, sigma_sq_obs, alert_emitted, deterministic_mode_forced.
+        """
+        if not self.is_initialized():
+            raise RuntimeError("GCC repository is not initialized. Run `devtorch init` first.")
+        from .variance import run_variance_monitor, VARIANCE_ALERT_EVENT
+        result = run_variance_monitor(self.gcc_dir, agent_variances)
+        if result.alert_emitted:
+            self._append_event(
+                event_type=VARIANCE_ALERT_EVENT,
+                payload={
+                    "f_max_live": result.f_max_live,
+                    "previous_f_max": result.previous_f_max,
+                    "sigma_sq_obs": result.sigma_sq_obs,
+                    "deterministic_mode_forced": result.deterministic_mode_forced,
+                },
+            )
+        return result.to_dict() if hasattr(result, "to_dict") else {
+            "f_max_live": result.f_max_live,
+            "previous_f_max": result.previous_f_max,
+            "sigma_sq_obs": result.sigma_sq_obs,
+            "alert_emitted": result.alert_emitted,
+            "deterministic_mode_forced": result.deterministic_mode_forced,
+        }
+
+    def variance_deterministic_mode_forced(self) -> bool:
+        """True when f_max_live was 0 at last variance monitor run (A2: force deterministic mode)."""
+        if not self.is_initialized():
+            return False
+        from .variance import variance_deterministic_mode_forced as check
+        return check(self.gcc_dir)
+
+    def invariant_check(
+        self,
+        operation: str = "merge",
+        branch_tips: Optional[Dict[str, str]] = None,
+        concepts_used: Optional[List[str]] = None,
+    ) -> List["InvariantFailure"]:
+        """Run invariant engine and return list of failures (empty if all pass)."""
+        if not self.is_initialized():
+            raise RuntimeError("GCC repository is not initialized. Run `devtorch init` first.")
+        from .invariants import (
+            InvariantContext,
+            InvariantEngine,
+            check_i1_commit_backed,
+            make_i3_semantic_handshake,
+            ConceptStore as InvariantConceptStore,
+        )
+        from .invariants import InvariantFailure
+        if branch_tips is None:
+            branch = self._current_branch()
+            tip = self._read_branch_tip(branch)
+            branch_tips = {branch: tip or ""}
+        context = InvariantContext(
+            operation=operation,
+            branch_tips=branch_tips,
+            concepts_used=concepts_used or [],
+        )
+        engine = InvariantEngine()
+        engine.register("I1", check_i1_commit_backed)
+        concept_store = InvariantConceptStore(self.gcc_dir)
+        engine.register("I3", make_i3_semantic_handshake(concept_store))
+        return engine.evaluate(self, context)
+
+    # Sprint 5 public API: REP, SIS, prompt, deltaf, RDP, disclosure
+
+    def rep_append(self, agent_id: str, round_id: int, payload: dict, trust: float = 0.5) -> int:
+        """Append a REP envelope to the local ledger; return sequence id."""
+        if not self.is_initialized():
+            raise RuntimeError("GCC repository is not initialized. Run `devtorch init` first.")
+        from .rep import REPLedger, create_envelope
+        envelope = create_envelope(agent_id, round_id, payload, trust)
+        ledger = REPLedger(self.gcc_dir)
+        return ledger.append(envelope, _now_iso())
+
+    def rep_replay_checksum(self) -> str:
+        """Deterministic checksum of REP ledger for replay verification."""
+        if not self.is_initialized():
+            return ""
+        from .rep import REPLedger
+        return REPLedger(self.gcc_dir).replay_checksum()
+
+    def sis_tc_run(self, corpus_path: Optional[Path] = None) -> "SISTCReport":
+        """Run SIS-TC evaluation; persist report under .GCC/sis/. corpus_path defaults to .GCC/sis/sis_tc_corpus.jsonl."""
+        if not self.is_initialized():
+            raise RuntimeError("GCC repository is not initialized. Run `devtorch init` first.")
+        from .sis import load_sis_tc_corpus, run_sis_tc_eval, SISTCReport, SIS_DIR_NAME, SIS_TC_CORPUS_NAME, SIS_TC_REPORT_NAME
+        path = corpus_path or (self.gcc_dir / SIS_DIR_NAME / SIS_TC_CORPUS_NAME)
+        corpus = load_sis_tc_corpus(path)
+        report = run_sis_tc_eval(corpus, classifier_fn=None, threshold=0.5)
+        (self.gcc_dir / SIS_DIR_NAME).mkdir(exist_ok=True)
+        (self.gcc_dir / SIS_DIR_NAME / SIS_TC_REPORT_NAME).write_text(
+            json.dumps(report.to_dict(), indent=2) + "\n", encoding="utf-8",
+        )
+        return report
+
+    def prompt_set(self, content: str, version: str = "v2.1") -> None:
+        """Store RACP_SYSTEM_PROMPT_v2.1 artifact."""
+        if not self.is_initialized():
+            raise RuntimeError("GCC repository is not initialized. Run `devtorch init` first.")
+        from .prompt_artifact import PromptArtifactStore
+        PromptArtifactStore(self.gcc_dir).set_prompt(content, version)
+
+    def prompt_get(self) -> Optional[str]:
+        """Return RACP system prompt content or None."""
+        if not self.is_initialized():
+            return None
+        from .prompt_artifact import PromptArtifactStore
+        return PromptArtifactStore(self.gcc_dir).get_prompt()
+
+    def deltaf_run(self, expiry_days: int = 90) -> "DeltaFReport":
+        """Run Δf estimation from current sensitivities; persist report and return it."""
+        if not self.is_initialized():
+            raise RuntimeError("GCC repository is not initialized. Run `devtorch init` first.")
+        from .deltaf import run_deltaf_estimation, DeltaFStore, DeltaFReport
+        events = self.list_sensitivities()
+        report = run_deltaf_estimation(events)
+        DeltaFStore(self.gcc_dir).save_report(report, _now_iso(), expiry_days)
+        return report
+
+    def rdp_spend(self, round_id: int, epsilon_cost: float) -> Tuple[bool, str]:
+        """Spend epsilon for round; returns (allowed: bool, event: str). Emits PRIVACY_BUDGET_EXHAUSTED if exhausted."""
+        if not self.is_initialized():
+            raise RuntimeError("GCC repository is not initialized. Run `devtorch init` first.")
+        from .rdp import RDPAccountant, PRIVACY_BUDGET_EXHAUSTED_EVENT
+        allowed, event = RDPAccountant(self.gcc_dir).spend(round_id, epsilon_cost)
+        if not allowed and event:
+            self._append_event(event_type=event, payload={"round_id": round_id})
+        return allowed, event
+
+    def rdp_read_only(self) -> bool:
+        """True if RDP budget exhausted (read-only mode)."""
+        if not self.is_initialized():
+            return False
+        from .rdp import RDPAccountant
+        return RDPAccountant(self.gcc_dir).is_read_only()
+
+    def disclosure_redact(self, text: str, padding_length: Optional[int] = None) -> str:
+        """Apply [PRIVATE] suppression and fixed-length padding."""
+        from .disclosure import DisclosurePolicy, apply_disclosure_policy
+        policy = DisclosurePolicy(padding_length=padding_length or 32)
+        return apply_disclosure_policy(text, policy)
+
+    # Sprint 6 debug views
+
+    def debug_timeline(self, filter_types: Optional[List[str]] = None) -> List[dict]:
+        """Read event log and return events, optionally filtered by event_type."""
+        if not self.is_initialized():
+            return []
+        event_log = self.gcc_dir / EVENT_LOG_NAME
+        if not event_log.exists():
+            return []
+        events = []
+        with event_log.open("r", encoding="utf-8") as f:
+            for line in f:
+                line = line.strip()
+                if not line:
+                    continue
+                try:
+                    obj = json.loads(line)
+                    if filter_types is None or obj.get("event_type") in filter_types:
+                        events.append(obj)
+                except json.JSONDecodeError:
+                    continue
+        return events
+
+    def debug_branch_compare(self, branch1: str, branch2: str) -> dict:
+        """Compare two branches: history (commit ids, messages), tip artifacts. Θ is global so no per-branch diff."""
+        if not self.is_initialized():
+            return {"branch1": [], "branch2": [], "theta": {}}
+        h1 = self.history(branch1)
+        h2 = self.history(branch2)
+        theta = self.get_theta()
+        return {
+            "branch1": [{"id": c.get("id"), "message": c.get("message"), "timestamp": c.get("timestamp")} for c in h1],
+            "branch2": [{"id": c.get("id"), "message": c.get("message"), "timestamp": c.get("timestamp")} for c in h2],
+            "theta": theta.get("coordination_vector", {}),
+        }
+
+    def debug_invariant_trace(self) -> List[dict]:
+        """Run invariant check and return failures as trace (invariant_id, message, actionable_fix)."""
+        if not self.is_initialized():
+            return []
+        failures = self.invariant_check()
+        return [
+            {"invariant_id": f.invariant_id, "message": f.message, "actionable_fix": f.actionable_fix}
+            for f in failures
+        ]
+
+    # Sprint 2 public API
+
+    def context_bundle(
+        self,
+        k_tokens: int,
+        policy: Optional[dict] = None,
+        branch: Optional[str] = None,
+        explain: bool = False,
+    ) -> dict:
+        """
+        Build a MECW-aware context bundle under an approximate token budget.
+
+        For Sprint 2 we keep the heuristic simple:
+        - Work on the given branch (or current HEAD branch).
+        - Traverse commits newest-first and include commit messages until
+          the approximate token budget is hit.
+        - Always include the current `main.md` header as a pinned artifact.
+
+        The returned bundle shape:
+        {
+          "k_tokens": int,
+          "approx_tokens_used": int,
+          "branch": str,
+          "included_commits": [commit_id, ...],
+          "artifacts": [
+             {"path": "main.md", "reason": "..."},
+             {"path": "commits/00000001.json", "reason": "..."},
+             ...
+          ],
+          "policy": policy or {},
+        }
+
+        The bundle is persisted under `.GCC/context_bundles/<timestamp>.json`.
+        """
+        if not self.is_initialized():
+            raise RuntimeError("GCC repository is not initialized. Run `devtorch init` first.")
+
+        if branch is None:
+            branch = self._current_branch()
+
+        history = self.history(branch)
+        approx_tokens_used = 0
+        included_commits: List[dict] = []
+
+        def _approx_tokens(text: str) -> int:
+            # Simple heuristic: 1 token ≈ 4 characters (rough).
+            return max(1, len(text) // 4)
+
+        # Always pin main.md header as context.
+        artifacts: List[dict] = []
+        main_md_path = self.gcc_dir / MAIN_MD_NAME
+        if main_md_path.exists():
+            header_preview = ""
+            with main_md_path.open("r", encoding="utf-8") as f:
+                for _ in range(5):
+                    line = f.readline()
+                    if not line:
+                        break
+                    header_preview += line
+            tokens = _approx_tokens(header_preview)
+            approx_tokens_used += tokens
+            artifacts.append(
+                {
+                    "path": str(MAIN_MD_NAME),
+                    "reason": "Pinned roadmap header for global migration context.",
+                    "approx_tokens": tokens,
+                }
+            )
+
+        # Walk commit history newest-first and include messages until budget is reached.
+        commits_dir = self.gcc_dir / COMMITS_DIR_NAME
+        for commit in history:
+            cid = commit.get("id")
+            message = commit.get("message", "")
+            # Use the commit message itself as the reason so the context prefix
+            # carries the actual reasoning text, not just a generic label.
+            reason = message.strip() or f"Reasoning milestone on branch `{branch}`."
+            commit_tokens = _approx_tokens(reason)
+            if approx_tokens_used + commit_tokens > max(k_tokens, 1):
+                break
+            approx_tokens_used += commit_tokens
+            included_commits.append(commit)
+            artifacts.append(
+                {
+                    "path": str(COMMITS_DIR_NAME + f"/{cid}.json"),
+                    "reason": reason,
+                    "approx_tokens": commit_tokens,
+                }
+            )
+
+        bundle = {
+            "k_tokens": int(k_tokens),
+            "approx_tokens_used": approx_tokens_used,
+            "branch": branch,
+            "included_commits": [c.get("id") for c in included_commits],
+            "artifacts": artifacts,
+            "policy": policy or {},
+        }
+
+        # Sprint 2: policy-aware retrieval scaffold.
+        # We don't yet enforce PROTECTED/PRIVATE redaction, but we attach
+        # the requested policy to the bundle for later sprints.
+
+        # Persist bundle
+        context_dir = self.gcc_dir / CONTEXT_DIR_NAME
+        context_dir.mkdir(exist_ok=True)
+        timestamp = _now_iso().replace(":", "-")
+        bundle_path = context_dir / f"bundle_{branch}_{timestamp}.json"
+        bundle_path.write_text(json.dumps(bundle, indent=2, sort_keys=True) + "\n", encoding="utf-8")
+
+        if explain:
+            bundle["bundle_path"] = str(bundle_path.relative_to(self.gcc_dir))
+
+        return bundle
+
+    def doctor(self) -> List[GCCIssue]:
+        """
+        Validate S0 invariants:
+        - `.GCC/` exists and contains core files.
+        - VERSION matches expected GCC_VERSION.
+        - Event log is valid JSONL and hash chain is intact.
+        """
+        issues: List[GCCIssue] = []
+
+        if not self.gcc_dir.exists():
+            issues.append(GCCIssue("layout", f"Missing `{GCC_DIR_NAME}/` directory. Run `devtorch init`."))
+            return issues
+
+        version_path = self.gcc_dir / VERSION_FILE_NAME
+        if not version_path.exists():
+            issues.append(GCCIssue("layout", f"Missing `{VERSION_FILE_NAME}` in `{GCC_DIR_NAME}/`."))
+        else:
+            version = version_path.read_text(encoding="utf-8").strip()
+            if version != GCC_VERSION:
+                issues.append(
+                    GCCIssue(
+                        "version",
+                        f"Unexpected GCC version `{version}` (expected `{GCC_VERSION}`).",
+                    )
+                )
+
+        # Check core artifacts
+        for name in (MAIN_MD_NAME, LOG_MD_NAME):
+            p = self.gcc_dir / name
+            if not p.exists():
+                issues.append(GCCIssue("layout", f"Missing `{name}` in `{GCC_DIR_NAME}/`."))
+
+        # Validate event log & hash chain
+        event_log = self.gcc_dir / EVENT_LOG_NAME
+        if not event_log.exists():
+            issues.append(GCCIssue("layout", f"Missing `{EVENT_LOG_NAME}` in `{GCC_DIR_NAME}/`."))
+        else:
+            chain_issues = _validate_event_log(event_log)
+            issues.extend(chain_issues)
+            sig_failures = verify_log(self.gcc_dir)
+            for failure in sig_failures:
+                line_no = failure["line_no"]
+                reason = failure["reason"]
+                event_hash = failure.get("event_hash")
+                msg = f"Signature failure on line {line_no}: {reason}"
+                if event_hash:
+                    msg += f" (event_hash={event_hash})"
+                issues.append(GCCIssue("signature", msg))
+
+        return issues
+
+    # Sprint 3 public API
+
+    def add_sensitivity(self, event: "SensitivityEvent") -> str:  # type: ignore[name-defined]
+        """
+        Persist *event*, ripple it into Θ, and emit a SENSITIVITY_ADDED audit event.
+        Returns the assigned event_id.
+        """
+        if not self.is_initialized():
+            raise RuntimeError("GCC repository is not initialized. Run `devtorch init` first.")
+
+        from .sensitivity import SensitivityStore
+        from .theta import make_theta_store
+
+        store = SensitivityStore(self.gcc_dir / SENSITIVITIES_DIR_NAME)
+        event_id = store.add(event)
+
+        make_theta_store(self.gcc_dir).ripple([event.to_dict()])
+
+        self._append_event(
+            event_type="SENSITIVITY_ADDED",
+            payload={
+                "event_id": event_id,
+                "target_concept": event.target_concept,
+                "disclosure_level": event.disclosure_level,
+                "source_node": event.source_node,
+            },
+        )
+        return event_id
+
+    def list_sensitivities(
+        self,
+        concept: Optional[str] = None,
+        disclosure_level: Optional[str] = None,
+        source_node: Optional[str] = None,
+    ) -> List[dict]:
+        """
+        Return stored sensitivity events as dicts, optionally filtered.
+
+        Parameters match SensitivityStore.filter(); all are wildcards when None.
+        """
+        if not self.is_initialized():
+            raise RuntimeError("GCC repository is not initialized. Run `devtorch init` first.")
+
+        from .sensitivity import SensitivityStore
+
+        store = SensitivityStore(self.gcc_dir / SENSITIVITIES_DIR_NAME)
+        return [
+            e.to_dict()
+            for e in store.filter(
+                concept=concept,
+                disclosure_level=disclosure_level,
+                source_node=source_node,
+            )
+        ]
+
+    def get_theta(self) -> dict:
+        """Return the current coordination vector Θ as a dict."""
+        if not self.is_initialized():
+            raise RuntimeError("GCC repository is not initialized. Run `devtorch init` first.")
+
+        from .theta import make_theta_store
+
+        return make_theta_store(self.gcc_dir).load()
+
+    def set_capability(self, cap: "OmegaCapability") -> None:  # type: ignore[name-defined]
+        """
+        Persist a new Ωᵢ capability declaration and emit a CAPABILITY_SET audit event.
+        """
+        if not self.is_initialized():
+            raise RuntimeError("GCC repository is not initialized. Run `devtorch init` first.")
+
+        from .capability import CapabilityStore
+
+        CapabilityStore(self.gcc_dir / CAPABILITIES_DIR_NAME).save(cap)
+        self._append_event(
+            event_type="CAPABILITY_SET",
+            payload={
+                "agent_id": cap.agent_id,
+                "schema_version": cap.schema_version,
+                "lipschitz_bound": cap.lipschitz_bound,
+                "pst_status": cap.pst_status,
+            },
+        )
+
+    def get_capability(self) -> Optional[dict]:
+        """Return the stored Ωᵢ as a dict, or None if none has been set."""
+        if not self.is_initialized():
+            raise RuntimeError("GCC repository is not initialized. Run `devtorch init` first.")
+
+        from .capability import CapabilityStore
+
+        cap = CapabilityStore(self.gcc_dir / CAPABILITIES_DIR_NAME).load()
+        return cap.to_dict() if cap is not None else None
+
+    def validate_capability(self, l_max: Optional[float] = None) -> dict:
+        """
+        Run A1 gate checks.
+
+        If Textual Mode is not allowed, emits a CAPABILITY_DEGRADED event.
+        Returns a dict representation of CapabilityValidationResult.
+        """
+        if not self.is_initialized():
+            raise RuntimeError("GCC repository is not initialized. Run `devtorch init` first.")
+
+        from .capability import CapabilityStore, L_MAX_DEFAULT
+
+        effective_l_max = l_max if l_max is not None else L_MAX_DEFAULT
+        result = CapabilityStore(self.gcc_dir / CAPABILITIES_DIR_NAME).validate(l_max=effective_l_max)
+
+        # A2: variance forces deterministic mode when f_max_live=0
+        if self.variance_deterministic_mode_forced():
+            import dataclasses as _dc
+            result = _dc.replace(
+                result,
+                textual_mode_allowed=False,
+                reasons=[*result.reasons, "A2: f_max=0; deterministic mode forced (variance)."],
+            )
+
+        if not result.textual_mode_allowed:
+            self._append_event(
+                event_type="CAPABILITY_DEGRADED",
+                payload={
+                    "agent_id": result.agent_id,
+                    "reasons": result.reasons,
+                    "pst_status": result.pst_status,
+                    "lipschitz_bound": (
+                        result.lipschitz_bound
+                        if result.lipschitz_bound != float("inf")
+                        else None
+                    ),
+                },
+            )
+
+        import dataclasses
+
+        return dataclasses.asdict(result)
+
+    def run_pst(
+        self,
+        agent_id: str,
+        run_fn,
+        n_prompts: int = 5,
+        n_repetitions: int = 3,
+        threshold: Optional[float] = None,
+        prompts: Optional[List[str]] = None,
+    ) -> dict:
+        """
+        Execute a PST run, persist the report artifact, update Ωᵢ PST fields,
+        and emit a PST_RUN audit event.  Returns the report as a dict.
+        """
+        if not self.is_initialized():
+            raise RuntimeError("GCC repository is not initialized. Run `devtorch init` first.")
+
+        import dataclasses as _dc
+
+        from .capability import (
+            CapabilityStore,
+            OmegaCapability,
+            PSTRunner,
+            PST_SCORE_THRESHOLD,
+        )
+
+        effective_threshold = threshold if threshold is not None else PST_SCORE_THRESHOLD
+        runner = PSTRunner(
+            agent_id=agent_id,
+            run_fn=run_fn,
+            n_prompts=n_prompts,
+            n_repetitions=n_repetitions,
+            threshold=effective_threshold,
+            prompts=prompts,
+        )
+        report = runner.run()
+
+        # Persist report artifact
+        pst_dir = self.gcc_dir / PST_REPORTS_DIR_NAME
+        pst_dir.mkdir(exist_ok=True)
+        ts = _now_iso().replace(":", "-")
+        report_path = pst_dir / f"pst_{agent_id}_{ts}.json"
+        report_path.write_text(
+            json.dumps(_dc.asdict(report), indent=2, sort_keys=True) + "\n",
+            encoding="utf-8",
+        )
+
+        # Update Ωᵢ if a capability declaration exists
+        cap_store = CapabilityStore(self.gcc_dir / CAPABILITIES_DIR_NAME)
+        cap = cap_store.load()
+        if cap is not None:
+            updated = _dc.replace(
+                cap,
+                pst_status=report.status,
+                pst_score=report.pst_score,
+                pst_n_prompts=report.n_prompts,
+                pst_n_repetitions=report.n_repetitions,
+                updated_at=_now_iso(),
+            )
+            cap_store.save(updated)
+
+        self._append_event(
+            event_type="PST_RUN",
+            payload={
+                "agent_id": agent_id,
+                "pst_score": report.pst_score,
+                "status": report.status,
+                "n_prompts": report.n_prompts,
+                "n_repetitions": report.n_repetitions,
+            },
+        )
+        return _dc.asdict(report)
+
+    def check_divergence(self, concept: str) -> List[dict]:
+        """
+        Detect reasoning divergence between agents for *concept*.
+        Returns list of DivergenceSignal dicts (serialisable).
+        """
+        if not self.is_initialized():
+            raise RuntimeError("GCC repository is not initialized.")
+        import dataclasses
+        from .divergence import DivergenceDetector
+        signals = DivergenceDetector(self).detect(concept=concept)
+        return [dataclasses.asdict(s) for s in signals]
+
+    def start_consolidation(self, concept: str) -> Optional[dict]:
+        """
+        Detect divergence and start a ConsolidationWorkflow for *concept*.
+        Returns the ConsolidationRecord as a dict, or None if no divergence.
+        """
+        if not self.is_initialized():
+            raise RuntimeError("GCC repository is not initialized.")
+        import dataclasses
+        from .divergence import DivergenceDetector
+        from .consolidation import ConsolidationWorkflow
+        signals = DivergenceDetector(self).detect(concept=concept)
+        if not signals:
+            return None
+        record = ConsolidationWorkflow(self).start(concept=concept, signals=signals)
+        return record.to_dict()
+
+    def reasoning_query(
+        self,
+        concept: str,
+        agent_id: Optional[str] = None,
+        scope: str = "branch",
+        k_tokens: int = 4000,
+    ) -> List[dict]:
+        """
+        Query agent reasoning for *concept*, optionally filtered by agent_id.
+        Returns list of ReasoningEntry dicts.
+        """
+        if not self.is_initialized():
+            raise RuntimeError("GCC repository is not initialized.")
+        import dataclasses
+        from .reasoning import ReasoningStore
+        entries = ReasoningStore(self).query(
+            concept=concept, agent_id=agent_id, scope=scope, k_tokens=k_tokens
+        )
+        return [dataclasses.asdict(e) for e in entries]
+
+    # Internal helpers
+
+    def _append_event(self, event_type: str, payload: dict) -> None:
+        def _build_line(current: bytes) -> bytes:
+            prior_hash = _last_event_hash_from_bytes(current)
+            event = {
+                "timestamp": _now_iso(),
+                "actor": "devtorch-cli",
+                "event_type": event_type,
+                "payload": payload,
+                "prior_hash": prior_hash,
+            }
+            event_bytes = json.dumps(event, sort_keys=True).encode("utf-8")
+            event_hash = hashlib.sha256(event_bytes).hexdigest()
+            event["hash"] = event_hash
+            event = sign_line_if_enabled(event, self.gcc_dir)
+            return (json.dumps(event, sort_keys=True) + "\n").encode("utf-8")
+
+        self._backend.read_and_append_atomic(EVENT_LOG_NAME, _build_line)
+
+    def _current_branch(self) -> str:
+        key = f"{REFS_DIR_NAME}/{HEAD_FILE_NAME}"
+        if not self._backend.exists(key):
+            return "main"
+        return self._read(REFS_DIR_NAME, HEAD_FILE_NAME).strip() or "main"
+
+    def _read_branch_tip(self, branch: str) -> Optional[str]:
+        key = f"{REFS_DIR_NAME}/{BRANCHES_DIR_NAME}/{branch}"
+        if not self._backend.exists(key):
+            return None
+        return self._read(REFS_DIR_NAME, BRANCHES_DIR_NAME, branch).strip() or None
+
+    def _write_branch_tip(self, branch: str, commit_id: str) -> None:
+        self._write(REFS_DIR_NAME, BRANCHES_DIR_NAME, branch, content=commit_id)
+
+    def _next_commit_id(self) -> str:
+        """
+        Deterministic, monotonic commit ID that does not depend on wall-clock time.
+        """
+        if self._backend.exists(COMMIT_INDEX_FILE_NAME):
+            raw = self._read(COMMIT_INDEX_FILE_NAME).strip()
+            try:
+                counter = int(raw)
+            except ValueError:
+                counter = 0
+        else:
+            counter = 0
+
+        counter += 1
+        self._write(COMMIT_INDEX_FILE_NAME, content=str(counter))
+
+        # Hex-encode with fixed width for readability
+        return f"{counter:08x}"
+
+
+def _now_iso() -> str:
+    return _dt.datetime.now(tz=_dt.timezone.utc).isoformat()
+
+
+def _last_event_hash_from_bytes(content: bytes) -> Optional[str]:
+    """Extract the hash field from the last non-empty JSONL line in content."""
+    last_line: Optional[str] = None
+    try:
+        text = content.decode("utf-8", errors="strict")
+    except UnicodeDecodeError:
+        return None
+    for line in text.splitlines():
+        if line.strip():
+            last_line = line
+    if not last_line:
+        return None
+    try:
+        return json.loads(last_line).get("hash")
+    except json.JSONDecodeError:
+        return None
+
+
+def _validate_event_log(path: Path) -> List[GCCIssue]:
+    issues: List[GCCIssue] = []
+    last_hash: Optional[str] = None
+    line_no = 0
+
+    with path.open("r", encoding="utf-8") as f:
+        for raw in f:
+            line_no += 1
+            line = raw.strip()
+            if not line:
+                continue
+            try:
+                obj = json.loads(line)
+            except json.JSONDecodeError:
+                issues.append(GCCIssue("event-log", f"Line {line_no}: invalid JSON."))
+                continue
+
+            # Required fields
+            for field in ("timestamp", "actor", "event_type", "payload", "hash"):
+                if field not in obj:
+                    issues.append(GCCIssue("event-log", f"Line {line_no}: missing field `{field}`."))
+
+            # Hash chain check
+            prior = obj.get("prior_hash")
+            if prior != last_hash and not (prior is None and last_hash is None):
+                issues.append(
+                    GCCIssue(
+                        "event-log",
+                        f"Line {line_no}: prior_hash mismatch (expected `{last_hash}`, got `{prior}`).",
+                    )
+                )
+
+            computed_bytes = json.dumps(
+                {
+                    "timestamp": obj.get("timestamp"),
+                    "actor": obj.get("actor"),
+                    "event_type": obj.get("event_type"),
+                    "payload": obj.get("payload"),
+                    "prior_hash": obj.get("prior_hash"),
+                },
+                sort_keys=True,
+            ).encode("utf-8")
+            computed_hash = hashlib.sha256(computed_bytes).hexdigest()
+            if obj.get("hash") != computed_hash:
+                issues.append(
+                    GCCIssue(
+                        "event-log",
+                        f"Line {line_no}: hash mismatch (expected `{computed_hash}`, got `{obj.get('hash')}`).",
+                    )
+                )
+
+            last_hash = obj.get("hash")
+
+    return issues
+