ltcai 8.1.0 → 8.2.0

package/latticeai/core/workspace_os.py

@@ -9,19 +9,47 @@ exported or compared without mutating the live knowledge graph.
 from __future__ import annotations
 
 import json
-import os
 import shutil
 import sqlite3
-import zipfile
 from collections import deque
-from datetime import datetime
 from pathlib import Path
 from typing import Any, Callable, Dict, Iterable, List, Optional
 
-from lattice_brain.runtime.contracts import realtime_event_contract, run_record_contract, workflow_run_contract
-
+# Extracted pure helpers (keeps this module smaller and focused on the store).
+from .workspace_os_utils import (
+    _atomic_write_json,
+    _deep_merge,
+    _json_hash,
+    _listify,
+    _now,
+    _safe_slug,
+    remove_skill_directory,
+)
+from .workspace_permissions import WorkspacePermissionManager, _member_role  # type: ignore
+from .workspace_timeline import WorkspaceTimeline
+from .workspace_plugins import WorkspacePluginManager
+from .workspace_memory import WorkspaceMemory
+from .workspace_snapshots import WorkspaceSnapshots
+from .workspace_graph_trace import WorkspaceGraphTrace
+from .workspace_runs import WorkspaceRuns
+from .workspace_skills import WorkspaceSkills
+
+__all__ = [
+    "WORKSPACE_OS_VERSION",
+    "WORKSPACE_TYPES",
+    "DEFAULT_WORKSPACE_ID",
+    "WORKSPACE_ROLES",
+    "WORKSPACE_PERMISSIONS",
+    "ROLE_PERMISSIONS",
+    "WORKSPACE_AREAS",
+    "ONBOARDING_STEPS",
+    "MEMORY_KINDS",
+    "EXECUTION_EVENT_TYPES",
+    "WorkspaceOSStore",
+    "remove_skill_directory",
+]
 
-WORKSPACE_OS_VERSION = "8.1.0"
+WORKSPACE_OS_VERSION = "8.2.0"
 
 # Workspace types separate single-user Personal workspaces from shared
 # Organization workspaces. Both keep the same local-first JSON store; the type
@@ -140,101 +168,6 @@ DEFAULT_AGENTS = [
 ]
 
 
-def _now() -> str:
-    return datetime.now().isoformat(timespec="seconds")
-
-
-def _safe_slug(raw: str) -> str:
-    value = "".join(ch if ch.isalnum() or ch in "-_." else "-" for ch in str(raw or "").strip())
-    value = "-".join(part for part in value.split("-") if part)
-    return (value or "item")[:96]
-
-
-def _json_hash(value: Any) -> str:
-    import hashlib
-
-    payload = json.dumps(value, ensure_ascii=False, sort_keys=True, default=str)
-    return hashlib.sha256(payload.encode("utf-8", errors="replace")).hexdigest()
-
-
-def _deep_merge(default: Any, loaded: Any) -> Any:
-    if isinstance(default, dict) and isinstance(loaded, dict):
-        merged = {key: _deep_merge(value, loaded.get(key)) for key, value in default.items()}
-        for key, value in loaded.items():
-            if key not in merged:
-                merged[key] = value
-        return merged
-    if loaded is None:
-        return default
-    return loaded
-
-
-def _atomic_write_json(path: Path, payload: Dict[str, Any]) -> None:
-    path.parent.mkdir(parents=True, exist_ok=True)
-    tmp_path = path.with_suffix(path.suffix + ".tmp")
-    tmp_path.write_text(json.dumps(payload, ensure_ascii=False, indent=2), encoding="utf-8")
-    os.replace(tmp_path, path)
-
-
-def _listify(value: Any) -> List[Any]:
-    return value if isinstance(value, list) else []
-
-
-def _snapshot_graph_import_payload(graph_payload: Dict[str, Any], *, workspace_id: Optional[str]) -> Dict[str, Any]:
-    """Convert the UI graph snapshot shape into the logical import artifact."""
-
-    nodes = []
-    for node in _listify((graph_payload or {}).get("nodes")):
-        node_id = node.get("id")
-        if not node_id:
-            continue
-        metadata = node.get("metadata") if isinstance(node.get("metadata"), dict) else {}
-        raw = node.get("raw") if isinstance(node.get("raw"), dict) else {}
-        if workspace_id and not metadata.get("workspace_id"):
-            metadata = {**metadata, "workspace_id": workspace_id}
-        nodes.append({
-            "id": node_id,
-            "type": node.get("type") or "Concept",
-            "title": node.get("title") or node.get("label") or node_id,
-            "summary": node.get("summary") or "",
-            "metadata_json": json.dumps(metadata, ensure_ascii=False),
-            "raw_json": json.dumps(raw, ensure_ascii=False),
-        })
-
-    edges = []
-    for edge in _listify((graph_payload or {}).get("edges")):
-        source = edge.get("from_node") or edge.get("from") or edge.get("source")
-        target = edge.get("to_node") or edge.get("to") or edge.get("target")
-        if not source or not target:
-            continue
-        edges.append({
-            "from_node": source,
-            "to_node": target,
-            "type": edge.get("type") or "related_to",
-            "weight": edge.get("weight") or 1.0,
-            "metadata_json": json.dumps(edge.get("metadata") or {}, ensure_ascii=False),
-        })
-
-    return {
-        "header": {"graph_schema_version": 1, "workspace_id": workspace_id, "source": "workspace_snapshot"},
-        "nodes": nodes,
-        "edges": edges,
-        "chunks": [],
-        "knowledge_sources": [],
-        "provenance": [],
-        "counts": {"nodes": len(nodes), "edges": len(edges)},
-    }
-
-
-def _parse_iso(value: Optional[str]) -> Optional[datetime]:
-    if not value:
-        return None
-    try:
-        return datetime.fromisoformat(str(value))
-    except (TypeError, ValueError):
-        return None
-
-
 class WorkspaceOSStore:
     """Local-first state store for Workspace OS APIs."""
 
@@ -251,6 +184,15 @@ class WorkspaceOSStore:
         # bus receives all workspace activity without per-call wiring.
         # Defaults to None → zero behavior change for existing callers/tests.
         self.event_sink = event_sink
+        # Composed managers (extracted to shrink god class per architecture rules).
+        self.permissions = WorkspacePermissionManager(self)
+        self._timeline = WorkspaceTimeline(self)
+        self.plugins = WorkspacePluginManager(self)
+        self.memory = WorkspaceMemory(self)
+        self.snapshots = WorkspaceSnapshots(self)
+        self.graph_trace = WorkspaceGraphTrace(self)
+        self.runs = WorkspaceRuns(self)
+        self.skills = WorkspaceSkills(self)
 
     def _connect_state_db(self) -> sqlite3.Connection:
         conn = sqlite3.connect(self.sqlite_path)
@@ -519,25 +461,7 @@ class WorkspaceOSStore:
         return state
 
     def record_timeline_event(self, area: str, event_type: str, payload: Dict[str, Any], workspace_id: Optional[str] = None) -> Dict[str, Any]:
-        state = self.load_state()
-        event = {
-            "id": f"timeline-{_json_hash([area, event_type, payload, _now()])[:16]}",
-            "area": area,
-            "event_type": event_type,
-            "timestamp": _now(),
-            "workspace_id": self._resolve_scope(workspace_id, state),
-            "payload": payload,
-        }
-        event["contract"] = realtime_event_contract({"seq": event["id"], "received_at": event["timestamp"], **event})
-        state.setdefault("timeline", []).append(event)
-        self.save_state(state)
-        if self.event_sink is not None:
-            try:
-                self.event_sink(event)
-            except Exception:
-                # Realtime delivery is best-effort and must never break a write.
-                pass
-        return event
+        return self._timeline.record_timeline_event(area, event_type, payload, workspace_id=workspace_id)
 
     def _emit_execution_event(
         self,
@@ -710,41 +634,17 @@ class WorkspaceOSStore:
 
     @staticmethod
     def _member_role(ws: Dict[str, Any], user_id: Optional[str]) -> Optional[str]:
-        if ws.get("type") == "personal":
-            return "owner"
-        owner = ws.get("owner_user_id")
-        # Local single-user / no-auth mode: an ownerless org is owned by the
-        # local user (who has no identity), so they can manage what they create.
-        if not owner and not user_id:
-            return "owner"
-        if user_id and user_id == owner:
-            return "owner"
-        for member in _listify(ws.get("members")):
-            if member.get("user_id") == user_id:
-                return member.get("role")
-        return None
+        # Delegated to extracted module (kept for any internal direct calls).
+        return _member_role(ws, user_id)
 
     def get_member_role(self, workspace_id: str, user_id: Optional[str]) -> Optional[str]:
-        ws = (self.load_state().get("workspaces") or {}).get(workspace_id)
-        if not ws:
-            raise FileNotFoundError(workspace_id)
-        return self._member_role(ws, user_id)
+        return self.permissions.get_member_role(workspace_id, user_id)
 
     def has_permission(self, workspace_id: str, user_id: Optional[str], permission: str) -> bool:
-        try:
-            role = self.get_member_role(workspace_id, user_id)
-        except FileNotFoundError:
-            return False
-        if role is None:
-            return False
-        return permission in ROLE_PERMISSIONS.get(role, set())
+        return self.permissions.has_permission(workspace_id, user_id, permission)
 
     def _require_permission(self, ws: Dict[str, Any], actor: Optional[str], permission: str) -> None:
-        role = self._member_role(ws, actor)
-        if role is None or permission not in ROLE_PERMISSIONS.get(role, set()):
-            raise PermissionError(
-                f"'{actor or 'anonymous'}' lacks '{permission}' on workspace '{ws.get('workspace_id')}'"
-            )
+        self.permissions.require_permission(ws, actor, permission)
 
     def _load_org(self, state: Dict[str, Any], workspace_id: str) -> Dict[str, Any]:
         ws = (state.get("workspaces") or {}).get(workspace_id)
@@ -788,26 +688,10 @@ class WorkspaceOSStore:
         return self._workspace_public(ws, actor)
 
     def add_member(self, workspace_id: str, *, user_id: str, role: str = "member", actor: Optional[str] = None) -> Dict[str, Any]:
-        if role not in WORKSPACE_ROLES:
-            raise ValueError(f"unknown role: {role}")
-        if not str(user_id or "").strip():
-            raise ValueError("user_id is required")
-        state = self.load_state()
-        ws = self._load_org(state, workspace_id)
-        self._require_permission(ws, actor, "manage_members")
-        members = ws.setdefault("members", [])
-        existing = next((m for m in members if m.get("user_id") == user_id), None)
-        if existing:
-            existing["role"] = role
-            existing["updated_at"] = _now()
-        else:
-            members.append({"user_id": user_id, "role": role, "added_at": _now()})
-        ws["updated_at"] = _now()
-        self.save_state(state)
-        self.record_timeline_event("workspace", "member_added", {"workspace_id": workspace_id, "user_id": user_id, "role": role})
-        return self._workspace_public(ws, actor)
+        return self.permissions.add_member(workspace_id, user_id=user_id, role=role, actor=actor)
 
     def update_member_role(self, workspace_id: str, *, user_id: str, role: str, actor: Optional[str] = None) -> Dict[str, Any]:
+        # delegate or keep simple for now (full impl in permissions if expanded)
         if role not in WORKSPACE_ROLES:
             raise ValueError(f"unknown role: {role}")
         state = self.load_state()
@@ -840,6 +724,10 @@ class WorkspaceOSStore:
         self.save_state(state)
         self.record_timeline_event("workspace", "member_removed", {"workspace_id": workspace_id, "user_id": user_id})
         return self._workspace_public(ws, actor)
+        ws["updated_at"] = _now()
+        self.save_state(state)
+        self.record_timeline_event("workspace", "member_removed", {"workspace_id": workspace_id, "user_id": user_id})
+        return self._workspace_public(ws, actor)
 
     def set_active_workspace(self, workspace_id: str, user_id: Optional[str] = None) -> Dict[str, Any]:
         state = self.load_state()
@@ -943,122 +831,13 @@ class WorkspaceOSStore:
     # ------------------------------------------------------------------
 
     def build_graph_trace(self, question: str, graph: Any, context: str = "", *, limit: int = 8) -> Dict[str, Any]:
-        if graph is None:
-            return {
-                "source_files": [],
-                "graph_nodes": [],
-                "graph_edges": [],
-                "confidence": 0.0,
-                "retrieval_metadata": {
-                    "query": question,
-                    "matched_nodes": 0,
-                    "graph_enabled": False,
-                    "context_chars": len(context or ""),
-                },
-            }
-
-        matches: List[Dict[str, Any]] = []
-        search_error = ""
-        try:
-            matches = graph.search(question, limit=limit).get("matches", [])
-        except Exception as exc:
-            search_error = str(exc)
-            matches = []
-
-        source_files: List[Dict[str, Any]] = []
-        seen_sources = set()
-        for match in matches:
-            meta = match.get("metadata") or {}
-            source = (
-                meta.get("relative_path")
-                or meta.get("file_path")
-                or meta.get("filename")
-                or meta.get("blob_path")
-                or meta.get("source")
-            )
-            if source and source not in seen_sources:
-                seen_sources.add(source)
-                source_files.append({
-                    "source": source,
-                    "node_id": match.get("id"),
-                    "node_title": match.get("title"),
-                    "node_type": match.get("type"),
-                    "jump": {
-                        "graph": f"/graph?node={match.get('id')}",
-                        "source": source,
-                    },
-                })
-
-        edges: List[Dict[str, Any]] = []
-        edge_seen = set()
-        for match in matches[:5]:
-            node_id = match.get("id")
-            if not node_id:
-                continue
-            try:
-                for edge in graph.neighbors(node_id).get("edges", []):
-                    key = (edge.get("from"), edge.get("to"), edge.get("type"))
-                    if key in edge_seen:
-                        continue
-                    edge_seen.add(key)
-                    edges.append(edge)
-                    if len(edges) >= 24:
-                        break
-            except Exception:
-                continue
+        return self.graph_trace.build_graph_trace(question, graph, context, limit=limit)
 
-        if matches:
-            confidence = min(0.95, 0.35 + min(len(matches), limit) / max(limit, 1) * 0.45 + (0.10 if edges else 0.0))
-        else:
-            confidence = 0.05 if context else 0.0
-
-        return {
-            "source_files": source_files,
-            "graph_nodes": matches,
-            "graph_edges": edges,
-            "confidence": round(confidence, 4),
-            "retrieval_metadata": {
-                "query": question,
-                "matched_nodes": len(matches),
-                "matched_edges": len(edges),
-                "graph_enabled": True,
-                "context_chars": len(context or ""),
-                "search_error": search_error,
-            },
-        }
-
-    def record_trace(
-        self,
-        *,
-        question: str,
-        response: str,
-        conversation_id: Optional[str],
-        user_email: Optional[str],
-        trace: Dict[str, Any],
-        workspace_id: Optional[str] = None,
-    ) -> Dict[str, Any]:
-        state = self.load_state()
-        trace_id = f"trace-{_json_hash([question, response, conversation_id, _now()])[:16]}"
-        record = {
-            "id": trace_id,
-            "question": question,
-            "response_preview": str(response or "")[:700],
-            "conversation_id": conversation_id,
-            "user_email": user_email,
-            "workspace_id": self._resolve_scope(workspace_id, state),
-            "created_at": _now(),
-            **trace,
-        }
-        state.setdefault("traces", []).append(record)
-        self.save_state(state)
-        self.record_timeline_event("graph", "answer_trace", {"trace_id": trace_id, "conversation_id": conversation_id})
-        return record
+    def record_trace(self, *args: Any, **kwargs: Any) -> Dict[str, Any]:
+        return self.graph_trace.record_trace(*args, **kwargs)
 
     def list_traces(self, conversation_id: Optional[str] = None, limit: int = 50, workspace_id: Optional[str] = None) -> Dict[str, Any]:
-        traces = self._scoped(_listify(self.load_state().get("traces")), workspace_id)
-        if conversation_id:
-            traces = [trace for trace in traces if trace.get("conversation_id") == conversation_id]
-        return {"traces": list(reversed(traces[-max(1, min(limit, 200)):]))}
+        return self.graph_trace.list_traces(conversation_id=conversation_id, limit=limit, workspace_id=workspace_id)
 
     # ------------------------------------------------------------------
     # Indexing dashboard
@@ -1150,89 +929,19 @@ class WorkspaceOSStore:
         models: Dict[str, Any],
         workspace_id: Optional[str] = None,
     ) -> Dict[str, Any]:
-        scope = self._resolve_scope(workspace_id)
-        graph_payload = {"nodes": [], "edges": []}
-        graph_stats = {}
-        local_sources = {"sources": []}
-        if graph is not None:
-            graph_payload = graph.graph(limit=2000)
-            graph_stats = graph.stats()
-            local_sources = graph.local_sources()
-        chat = list(history or [])
-        snapshot_body = {
-            "version": WORKSPACE_OS_VERSION,
-            "name": name or "Workspace snapshot",
-            "created_at": _now(),
-            "workspace": scope,
-            "workspace_id": scope,
-            "graph": graph_payload,
-            "graph_stats": graph_stats,
-            "chat": chat,
-            "settings": settings,
-            "indexed_folders": local_sources.get("sources", []),
-            "models": models,
-        }
-        snapshot_id = f"snapshot-{datetime.now().strftime('%Y%m%d%H%M%S')}-{_json_hash(snapshot_body)[:10]}"
-        snapshot_body["id"] = snapshot_id
-        path = self.snapshots_dir / f"{snapshot_id}.json"
-        _atomic_write_json(path, snapshot_body)
-
-        state = self.load_state()
-        meta = {
-            "id": snapshot_id,
-            "name": snapshot_body["name"],
-            "created_at": snapshot_body["created_at"],
-            "workspace_id": scope,
-            "path": str(path),
-            "node_count": len(graph_payload.get("nodes") or []),
-            "edge_count": len(graph_payload.get("edges") or []),
-            "chat_count": len(chat),
-            "model_count": len(models.get("loaded_models") or []),
-            "indexed_folder_count": len(local_sources.get("sources") or []),
-        }
-        state.setdefault("snapshots", []).append(meta)
-        self.save_state(state)
-        self.record_timeline_event("snapshot", "snapshot_saved", {"snapshot_id": snapshot_id, "name": name})
-        return {"snapshot": meta}
+        return self.snapshots.create_snapshot(name=name, graph=graph, history=history, settings=settings, models=models, workspace_id=workspace_id)
 
     def list_snapshots(self, workspace_id: Optional[str] = None) -> Dict[str, Any]:
-        snapshots = self._scoped(_listify(self.load_state().get("snapshots")), workspace_id)
-        return {"snapshots": list(reversed(snapshots))}
+        return self.snapshots.list_snapshots(workspace_id=workspace_id)
 
     def get_snapshot(self, snapshot_id: str) -> Dict[str, Any]:
-        path = self.snapshots_dir / f"{_safe_slug(snapshot_id)}.json"
-        if not path.exists():
-            state = self.load_state()
-            meta = next((item for item in _listify(state.get("snapshots")) if item.get("id") == snapshot_id), None)
-            if meta:
-                path = Path(meta.get("path") or path)
-        if not path.exists():
-            raise FileNotFoundError(snapshot_id)
-        return json.loads(path.read_text(encoding="utf-8"))
+        return self.snapshots.get_snapshot(snapshot_id)
 
     def snapshot_view(self, snapshot_id: str, area: str) -> Dict[str, Any]:
-        snapshot = self.get_snapshot(snapshot_id)
-        if area == "graph":
-            return {"snapshot_id": snapshot_id, "graph": snapshot.get("graph") or {}, "graph_stats": snapshot.get("graph_stats") or {}}
-        if area == "chat":
-            return {"snapshot_id": snapshot_id, "chat": snapshot.get("chat") or []}
-        if area == "decision":
-            nodes = (snapshot.get("graph") or {}).get("nodes") or []
-            return {"snapshot_id": snapshot_id, "decisions": [node for node in nodes if node.get("type") == "Decision"]}
-        return {"snapshot_id": snapshot_id, "snapshot": snapshot}
+        return self.snapshots.snapshot_view(snapshot_id, area)
 
     def export_snapshot(self, snapshot_id: str) -> Dict[str, Any]:
-        snapshot = self.get_snapshot(snapshot_id)
-        export_path = self.exports_dir / f"{_safe_slug(snapshot_id)}.zip"
-        with zipfile.ZipFile(export_path, "w", compression=zipfile.ZIP_DEFLATED) as zf:
-            zf.writestr("snapshot.json", json.dumps(snapshot, ensure_ascii=False, indent=2))
-            zf.writestr("graph.json", json.dumps(snapshot.get("graph") or {}, ensure_ascii=False, indent=2))
-            zf.writestr("chat.json", json.dumps(snapshot.get("chat") or [], ensure_ascii=False, indent=2))
-            zf.writestr("settings.json", json.dumps(snapshot.get("settings") or {}, ensure_ascii=False, indent=2))
-            zf.writestr("indexed_folders.json", json.dumps(snapshot.get("indexed_folders") or [], ensure_ascii=False, indent=2))
-            zf.writestr("models.json", json.dumps(snapshot.get("models") or {}, ensure_ascii=False, indent=2))
-        self.record_timeline_event("snapshot", "snapshot_exported", {"snapshot_id": snapshot_id, "path": str(export_path)})
-        return {"snapshot_id": snapshot_id, "export_path": str(export_path), "bytes": export_path.stat().st_size}
+        return self.snapshots.export_snapshot(snapshot_id)
 
     def restore_snapshot(
         self,
@@ -1242,109 +951,10 @@ class WorkspaceOSStore:
         workspace_id: Optional[str] = None,
         user_email: Optional[str] = None,
     ) -> Dict[str, Any]:
-        """Restore a snapshot additively, preserving all current user data.
-
-        v4 snapshots are immutable checkpoints. Restoring one must not delete
-        newer graph nodes, chat history, memories, workspaces, or settings, so
-        this operation imports the snapshot graph in ``merge`` mode and records a
-        durable restore event. It is a real restore path for lost/missing graph
-        data, with rollback safety because current state remains intact.
-        """
-
-        snapshot = self.get_snapshot(snapshot_id)
-        scope = self._resolve_scope(workspace_id or snapshot.get("workspace_id"))
-        if graph is None or not hasattr(graph, "import_graph_data"):
-            raise ValueError("knowledge graph import is required for snapshot restore")
-        artifact = _snapshot_graph_import_payload(snapshot.get("graph") or {}, workspace_id=scope)
-        import_result = graph.import_graph_data(artifact, mode="merge", dry_run=False)
-        restore_id = f"restore-{datetime.now().strftime('%Y%m%d%H%M%S')}-{_json_hash([snapshot_id, scope, user_email, _now()])[:10]}"
-        record = {
-            "id": restore_id,
-            "snapshot_id": snapshot_id,
-            "workspace_id": scope,
-            "restored_at": _now(),
-            "restored_by": user_email,
-            "mode": "merge",
-            "graph": import_result,
-            "settings_preserved": True,
-            "chat_preserved": True,
-        }
-        state = self.load_state()
-        state.setdefault("snapshot_restores", []).append(record)
-        self.save_state(state)
-        self.record_timeline_event(
-            "snapshot",
-            "snapshot_restored",
-            {"snapshot_id": snapshot_id, "restore_id": restore_id, "mode": "merge", "graph": import_result},
-            workspace_id=scope,
-        )
-        return {"restored": True, "restore": record}
+        return self.snapshots.restore_snapshot(snapshot_id, graph=graph, workspace_id=workspace_id, user_email=user_email)
 
     def compare_snapshots(self, before_id: str, after_id: str) -> Dict[str, Any]:
-        before = self.get_snapshot(before_id)
-        after = self.get_snapshot(after_id)
-        before_nodes = {node.get("id"): node for node in (before.get("graph") or {}).get("nodes") or [] if node.get("id")}
-        after_nodes = {node.get("id"): node for node in (after.get("graph") or {}).get("nodes") or [] if node.get("id")}
-
-        def edge_key(edge: Dict[str, Any]) -> str:
-            return "|".join(str(edge.get(key) or "") for key in ("from", "to", "type"))
-
-        before_edges = {edge_key(edge): edge for edge in (before.get("graph") or {}).get("edges") or []}
-        after_edges = {edge_key(edge): edge for edge in (after.get("graph") or {}).get("edges") or []}
-
-        added_nodes = [after_nodes[key] for key in sorted(set(after_nodes) - set(before_nodes))]
-        removed_nodes = [before_nodes[key] for key in sorted(set(before_nodes) - set(after_nodes))]
-        changed_nodes = [
-            {"before": before_nodes[key], "after": after_nodes[key]}
-            for key in sorted(set(before_nodes) & set(after_nodes))
-            if _json_hash(before_nodes[key]) != _json_hash(after_nodes[key])
-        ]
-        added_edges = [after_edges[key] for key in sorted(set(after_edges) - set(before_edges))]
-        removed_edges = [before_edges[key] for key in sorted(set(before_edges) - set(after_edges))]
-
-        before_decisions = {key: value for key, value in before_nodes.items() if value.get("type") == "Decision"}
-        after_decisions = {key: value for key, value in after_nodes.items() if value.get("type") == "Decision"}
-        decisions_changed = [
-            {"before": before_decisions.get(key), "after": after_decisions.get(key)}
-            for key in sorted(set(before_decisions) | set(after_decisions))
-            if _json_hash(before_decisions.get(key)) != _json_hash(after_decisions.get(key))
-        ]
-
-        return {
-            "before": before_id,
-            "after": after_id,
-            "nodes_added": added_nodes,
-            "nodes_removed": removed_nodes,
-            "nodes_changed": changed_nodes,
-            "edges_added": added_edges,
-            "edges_removed": removed_edges,
-            "decisions_changed": decisions_changed,
-            "summary": {
-                "nodes_added": len(added_nodes),
-                "nodes_removed": len(removed_nodes),
-                "nodes_changed": len(changed_nodes),
-                "edges_added": len(added_edges),
-                "edges_removed": len(removed_edges),
-                "decisions_changed": len(decisions_changed),
-            },
-        }
-
-    def timeline(self, audit_events: Optional[Iterable[Dict[str, Any]]] = None, limit: int = 100, workspace_id: Optional[str] = None) -> Dict[str, Any]:
-        state = self.load_state()
-        events: List[Dict[str, Any]] = []
-        events.extend(self._scoped(_listify(state.get("timeline")), workspace_id))
-        for snapshot in self._scoped(_listify(state.get("snapshots")), workspace_id):
-            events.append({"area": "snapshot", "event_type": "snapshot", "timestamp": snapshot.get("created_at"), "workspace_id": self._record_workspace(snapshot), "payload": snapshot})
-        for trace in self._scoped(_listify(state.get("traces")), workspace_id):
-            events.append({"area": "graph", "event_type": "answer_trace", "timestamp": trace.get("created_at"), "workspace_id": self._record_workspace(trace), "payload": trace})
-        for run in self._scoped(_listify(state.get("agent_runs")), workspace_id):
-            events.append({"area": "agent", "event_type": "agent_run", "timestamp": run.get("created_at"), "workspace_id": self._record_workspace(run), "payload": run})
-        for workflow in self._scoped(_listify(state.get("workflows")), workspace_id):
-            events.append({"area": "workflow", "event_type": "workflow", "timestamp": workflow.get("created_at"), "workspace_id": self._record_workspace(workflow), "payload": workflow})
-        for audit in audit_events or []:
-            events.append({"area": "audit", "event_type": audit.get("event_type") or "audit", "timestamp": audit.get("timestamp"), "payload": audit})
-        events.sort(key=lambda item: item.get("timestamp") or "", reverse=True)
-        return {"events": events[: max(1, min(limit, 500))]}
+        return self.snapshots.compare_snapshots(before_id, after_id)
 
     # ------------------------------------------------------------------
     # Personal memory
@@ -1362,54 +972,13 @@ class WorkspaceOSStore:
         graph: Any = None,
         workspace_id: Optional[str] = None,
     ) -> Dict[str, Any]:
-        if kind not in MEMORY_KINDS:
-            raise ValueError(f"unknown memory kind: {kind}")
-        if not str(content or "").strip():
-            raise ValueError("content is required")
-        state = self.load_state()
-        memories = _listify(state.get("memories"))
-        now = _now()
-        memory_id = memory_id or f"memory-{_json_hash([kind, content, user_email, now])[:16]}"
-        existing = next((item for item in memories if item.get("id") == memory_id), None)
-        record = existing or {
-            "id": memory_id,
-            "created_at": now,
-        }
-        record.update({
-            "kind": kind,
-            "content": content,
-            "user_email": user_email,
-            "tags": tags or [],
-            "metadata": {**(metadata or {}), "memory_scope": kind},
-            "workspace_id": self._resolve_scope(workspace_id, state) if existing is None else self._record_workspace(record),
-            "updated_at": now,
-        })
-        if graph is not None:
-            try:
-                ingested = graph.ingest_event(
-                    "Memory",
-                    f"{kind}: {content[:80]}",
-                    user_email=user_email,
-                    source="workspace_os",
-                    metadata={"memory_id": memory_id, "kind": kind, "tags": tags or []},
-                )
-                record["graph_node_id"] = ingested.get("node_id")
-            except Exception as exc:
-                record["graph_error"] = str(exc)
-        if existing is None:
-            memories.append(record)
-        state["memories"] = memories
-        self.save_state(state)
-        self.record_timeline_event("memory", "memory_upserted", {"memory_id": memory_id, "kind": kind}, workspace_id=record.get("workspace_id"))
-        return record
+        return self.memory.upsert_memory(
+            kind=kind, content=content, user_email=user_email, tags=tags,
+            memory_id=memory_id, metadata=metadata, graph=graph, workspace_id=workspace_id
+        )
 
     def list_memories(self, user_email: Optional[str] = None, kind: Optional[str] = None, workspace_id: Optional[str] = None) -> Dict[str, Any]:
-        memories = self._scoped(_listify(self.load_state().get("memories")), workspace_id)
-        if user_email:
-            memories = [item for item in memories if item.get("user_email") in {None, user_email}]
-        if kind:
-            memories = [item for item in memories if item.get("kind") == kind]
-        return {"memories": list(reversed(memories))}
+        return self.memory.list_memories(user_email=user_email, kind=kind, workspace_id=workspace_id)
 
     def search_memories(self, query: str, user_email: Optional[str] = None, limit: int = 20, workspace_id: Optional[str] = None) -> Dict[str, Any]:
         q = str(query or "").lower().strip()
@@ -1486,432 +1055,63 @@ class WorkspaceOSStore:
     # Agent and workflow graph
     # ------------------------------------------------------------------
 
-    def list_agents(self, workspace_id: Optional[str] = None) -> Dict[str, Any]:
-        state = self.load_state()
-        runs = self._scoped(_listify(state.get("agent_runs")), workspace_id)
-        return {"agents": _listify(state.get("agents")), "runs": list(reversed(runs[-100:]))}
+    def list_agents(self, *args: Any, **kwargs: Any) -> Dict[str, Any]:
+        return self.runs.list_agents(*args, **kwargs)
 
-    def record_agent_run(
-        self,
-        *,
-        agent_id: str,
-        status: str,
-        input_text: str,
-        output_text: str,
-        user_email: Optional[str],
-        timeline: Optional[List[Dict[str, Any]]] = None,
-        relationships: Optional[List[str]] = None,
-        handoffs: Optional[List[Dict[str, Any]]] = None,
-        context_packets: Optional[List[Dict[str, Any]]] = None,
-        plan: Optional[List[Dict[str, Any]]] = None,
-        plan_review: Optional[Dict[str, Any]] = None,
-        review_history: Optional[List[Dict[str, Any]]] = None,
-        retry_history: Optional[List[Dict[str, Any]]] = None,
-        memory_snapshots: Optional[List[Dict[str, Any]]] = None,
-        graph: Any = None,
-        workspace_id: Optional[str] = None,
-        mode: str = "simulation",
-    ) -> Dict[str, Any]:
-        state = self.load_state()
-        resolved_workspace = self._resolve_scope(workspace_id, state)
-        run = {
-            "id": f"agent-run-{_json_hash([agent_id, input_text, output_text, _now()])[:16]}",
-            "record_schema_version": 2,
-            "agent_id": agent_id,
-            "mode": mode,
-            "status": status,
-            "input": input_text,
-            "output_preview": output_text[:1000],
-            "user_email": user_email,
-            "workspace_id": resolved_workspace,
-            "relationships": relationships or [],
-            "timeline": timeline or [],
-            "handoffs": handoffs or [],
-            "context_packets": context_packets or [],
-            "plan": plan or [],
-            "plan_review": plan_review or {},
-            "review_history": review_history or [],
-            "retry_history": retry_history or [],
-            "memory_snapshots": memory_snapshots or [],
-            "created_at": _now(),
-        }
-        if mode == "simulation":
-            # Simulated runs are replay scaffolding, not experiences — they must
-            # never enter the knowledge graph as real provenance.
-            run["graph_node_id"] = None
-            run["graph_skipped"] = "simulation runs are not recorded in the knowledge graph"
-        elif graph is not None:
-            try:
-                ingested = graph.ingest_event(
-                    "AgentRun",
-                    f"{agent_id} {status}",
-                    user_email=user_email,
-                    source="workspace_os",
-                    metadata={"run_id": run["id"], "agent_id": agent_id, "status": status, "mode": mode},
-                )
-                run["graph_node_id"] = ingested.get("node_id")
-            except Exception as exc:
-                run["graph_error"] = str(exc)
-        if handoffs:
-            stored_handoffs = state.setdefault("handoffs", [])
-            for handoff in handoffs:
-                stored = {
-                    **handoff,
-                    "run_id": run["id"],
-                    "workspace_id": resolved_workspace,
-                }
-                stored_handoffs.append(stored)
-            state["handoffs"] = stored_handoffs
-        state.setdefault("agent_runs", []).append(run)
-        self.save_state(state)
-        self._emit_replayable_timeline_events(area="agent", run_id=run["id"], timeline=run["timeline"], workspace_id=resolved_workspace)
-        if status == "failed":
-            self._emit_execution_event(area="agent", event_type="execution_failed", payload={"run_id": run["id"], "agent_id": agent_id, "status": status}, workspace_id=resolved_workspace)
-        self.record_timeline_event("agent", "agent_run", {"run_id": run["id"], "agent_id": agent_id, "status": status}, workspace_id=resolved_workspace)
-        run["contract"] = run_record_contract(run)
-        state = self.load_state()
-        for item in _listify(state.get("agent_runs")):
-            if item.get("id") == run["id"]:
-                item["contract"] = run["contract"]
-                break
-        self.save_state(state)
-        return run
+    def record_agent_run(self, *args: Any, **kwargs: Any) -> Dict[str, Any]:
+        return self.runs.record_agent_run(*args, **kwargs)
 
-    def update_agent_run(
-        self,
-        run_id: str,
-        *,
-        workspace_id: Optional[str] = None,
-        graph: Any = None,
-        patch: Optional[Dict[str, Any]] = None,
-        **fields: Any,
-    ) -> Dict[str, Any]:
-        """Patch a persisted agent run without changing its id.
+    def update_agent_run(self, *args: Any, **kwargs: Any) -> Dict[str, Any]:
+        return self.runs.update_agent_run(*args, **kwargs)
 
-        Async execution creates a durable queued/running row before work starts,
-        then updates that same row as progress, cancellation, or a terminal
-        result arrives. This keeps old run lists/read APIs compatible while
-        avoiding duplicate "placeholder + final" records.
-        """
-        updates = {**(patch or {}), **fields}
-        state = self.load_state()
-        run = next((item for item in _listify(state.get("agent_runs")) if item.get("id") == run_id), None)
-        if run is None or (workspace_id and self._record_workspace(run) != str(workspace_id)):
-            raise FileNotFoundError(run_id)
-        resolved_workspace = self._record_workspace(run)
-        old_timeline_len = len(run.get("timeline") or [])
-
-        output_text = updates.pop("output_text", None)
-        if output_text is not None:
-            run["output_preview"] = str(output_text)[:1000]
-        for key, value in updates.items():
-            run[key] = value
-        status = str(run.get("status") or "")
-        run["updated_at"] = _now()
-        if status in RUN_TERMINAL_STATUSES:
-            run.setdefault("completed_at", _now())
-
-        handoffs = updates.get("handoffs")
-        if isinstance(handoffs, list):
-            stored_handoffs = [
-                item for item in _listify(state.get("handoffs"))
-                if item.get("run_id") != run_id
-            ]
-            for handoff in handoffs:
-                if isinstance(handoff, dict):
-                    stored_handoffs.append({**handoff, "run_id": run_id, "workspace_id": resolved_workspace})
-            state["handoffs"] = stored_handoffs
-
-        if (
-            status in RUN_TERMINAL_STATUSES
-            and run.get("mode") != "simulation"
-            and graph is not None
-            and not run.get("graph_node_id")
-        ):
-            try:
-                ingested = graph.ingest_event(
-                    "AgentRun",
-                    f"{run.get('agent_id')} {status}",
-                    user_email=run.get("user_email"),
-                    source="workspace_os",
-                    metadata={
-                        "run_id": run_id,
-                        "agent_id": run.get("agent_id"),
-                        "status": status,
-                        "mode": run.get("mode"),
-                    },
-                )
-                run["graph_node_id"] = ingested.get("node_id")
-            except Exception as exc:
-                run["graph_error"] = str(exc)
+    def get_agent_run(self, *args: Any, **kwargs: Any) -> Dict[str, Any]:
+        return self.runs.get_agent_run(*args, **kwargs)
 
-        self.save_state(state)
-        run["contract"] = run_record_contract(run)
-        state = self.load_state()
-        for item in _listify(state.get("agent_runs")):
-            if item.get("id") == run_id:
-                item["contract"] = run["contract"]
-                break
-        self.save_state(state)
+    def list_handoffs(self, *args: Any, **kwargs: Any) -> Dict[str, Any]:
+        return self.runs.list_handoffs(*args, **kwargs)
 
-        timeline = run.get("timeline") or []
-        if len(timeline) > old_timeline_len:
-            self._emit_replayable_timeline_events(
-                area="agent",
-                run_id=run_id,
-                timeline=timeline[old_timeline_len:],
-                workspace_id=resolved_workspace,
-            )
-        if status == "failed":
-            self._emit_execution_event(area="agent", event_type="execution_failed", payload={"run_id": run_id, "agent_id": run.get("agent_id"), "status": status}, workspace_id=resolved_workspace)
-        elif status == "cancelled":
-            self._emit_execution_event(area="agent", event_type="execution_cancelled", payload={"run_id": run_id, "agent_id": run.get("agent_id"), "status": status}, workspace_id=resolved_workspace)
-        elif status == "interrupted":
-            self._emit_execution_event(area="agent", event_type="execution_interrupted", payload={"run_id": run_id, "agent_id": run.get("agent_id"), "status": status}, workspace_id=resolved_workspace)
-        self.record_timeline_event("agent", "agent_run_update", {"run_id": run_id, "agent_id": run.get("agent_id"), "status": status}, workspace_id=resolved_workspace)
-        return run
-
-    def get_agent_run(self, run_id: str, workspace_id: Optional[str] = None) -> Dict[str, Any]:
-        run = next((item for item in _listify(self.load_state().get("agent_runs")) if item.get("id") == run_id), None)
-        if not run or (workspace_id and self._record_workspace(run) != str(workspace_id)):
-            raise FileNotFoundError(run_id)
-        return run
-
-    def list_handoffs(self, workspace_id: Optional[str] = None, run_id: Optional[str] = None) -> Dict[str, Any]:
-        handoffs = self._scoped(_listify(self.load_state().get("handoffs")), workspace_id)
-        if run_id:
-            handoffs = [item for item in handoffs if item.get("run_id") == run_id]
-        return {"handoffs": list(reversed(handoffs[-200:]))}
-
-    def create_workflow(
-        self,
-        *,
-        name: str,
-        steps: List[Dict[str, Any]],
-        user_email: Optional[str],
-        metadata: Optional[Dict[str, Any]] = None,
-        graph: Any = None,
-        workspace_id: Optional[str] = None,
-        nodes: Optional[List[Dict[str, Any]]] = None,
-    ) -> Dict[str, Any]:
-        state = self.load_state()
-        workflow = {
-            "id": f"workflow-{_json_hash([name, steps, user_email, _now()])[:16]}",
-            "name": name or "Untitled workflow",
-            "steps": steps,
-            "user_email": user_email,
-            "workspace_id": self._resolve_scope(workspace_id, state),
-            "metadata": metadata or {},
-            "events": [{"type": "created", "timestamp": _now()}],
-            "created_at": _now(),
-            "updated_at": _now(),
-        }
-        # Workflow Designer stores a typed-node graph alongside the legacy
-        # ``steps`` list so older history keeps working and new editors get nodes.
-        if nodes is not None:
-            workflow["nodes"] = nodes
-        if graph is not None:
-            try:
-                ingested = graph.ingest_event(
-                    "Workflow",
-                    workflow["name"],
-                    user_email=user_email,
-                    source="workspace_os",
-                    metadata={"workflow_id": workflow["id"], "steps": steps},
-                )
-                workflow["graph_node_id"] = ingested.get("node_id")
-            except Exception as exc:
-                workflow["graph_error"] = str(exc)
-        state.setdefault("workflows", []).append(workflow)
-        self.save_state(state)
-        self.record_timeline_event("workflow", "workflow_created", {"workflow_id": workflow["id"], "name": workflow["name"]})
-        return workflow
+    def create_workflow(self, *args: Any, **kwargs: Any) -> Dict[str, Any]:
+        return self.runs.create_workflow(*args, **kwargs)
 
-    def record_workflow_run(
-        self,
-        *,
-        workflow_id: Optional[str],
-        name: str,
-        status: str,
-        timeline: List[Dict[str, Any]],
-        outputs: Optional[Dict[str, Any]] = None,
-        user_email: Optional[str] = None,
-        graph: Any = None,
-        workspace_id: Optional[str] = None,
-        mode: str = "simulation",
-        pause: Optional[Dict[str, Any]] = None,
-    ) -> Dict[str, Any]:
-        """Persist a Workflow Designer execution into local-first run history."""
-        state = self.load_state()
-        resolved_workspace = self._resolve_scope(workspace_id, state)
-        run = {
-            "id": f"workflow-run-{_json_hash([workflow_id, name, status, _now()])[:16]}",
-            "record_schema_version": 2,
-            "workflow_id": workflow_id,
-            "name": name or "workflow",
-            "mode": mode,
-            "status": status,
-            "timeline": timeline or [],
-            "outputs": outputs or {},
-            "user_email": user_email,
-            "workspace_id": resolved_workspace,
-            "created_at": _now(),
-        }
-        if pause:
-            run["pause"] = pause
-        if mode == "simulation":
-            # Record-only node runners do no real work; their runs must not be
-            # written into the knowledge graph as if they were real executions.
-            run["graph_node_id"] = None
-            run["graph_skipped"] = "simulation runs are not recorded in the knowledge graph"
-        elif graph is not None:
-            try:
-                ingested = graph.ingest_event(
-                    "WorkflowRun",
-                    f"{run['name']} {status}",
-                    user_email=user_email,
-                    source="workspace_os",
-                    metadata={"run_id": run["id"], "workflow_id": workflow_id, "status": status, "mode": mode},
-                )
-                run["graph_node_id"] = ingested.get("node_id")
-            except Exception as exc:
-                run["graph_error"] = str(exc)
-        state.setdefault("workflow_runs", []).append(run)
-        # Attach the run id to the workflow's event log for cross-linking.
-        for wf in _listify(state.get("workflows")):
-            if wf.get("id") == workflow_id:
-                wf.setdefault("events", []).append({"type": "run", "timestamp": _now(), "payload": {"run_id": run["id"], "status": status}})
-                wf["updated_at"] = _now()
-                break
-        self.save_state(state)
-        self._emit_execution_event(area="workflow", event_type="workflow_started", payload={"run_id": run["id"], "workflow_id": workflow_id, "name": name}, workspace_id=resolved_workspace)
-        self._emit_replayable_timeline_events(area="workflow", run_id=run["id"], timeline=run["timeline"], workspace_id=resolved_workspace)
-        if status == "failed":
-            self._emit_execution_event(area="workflow", event_type="execution_failed", payload={"run_id": run["id"], "workflow_id": workflow_id, "status": status}, workspace_id=resolved_workspace)
-        elif status in {"ok", "partial"}:
-            self._emit_execution_event(area="workflow", event_type="workflow_completed", payload={"run_id": run["id"], "workflow_id": workflow_id, "status": status}, workspace_id=resolved_workspace)
-        self.record_timeline_event("workflow", "workflow_run", {"run_id": run["id"], "workflow_id": workflow_id, "status": status}, workspace_id=resolved_workspace)
-        run["contract"] = workflow_run_contract(run)
-        state = self.load_state()
-        for item in _listify(state.get("workflow_runs")):
-            if item.get("id") == run["id"]:
-                item["contract"] = run["contract"]
-                break
-        self.save_state(state)
-        return run
+    def record_workflow_run(self, *args: Any, **kwargs: Any) -> Dict[str, Any]:
+        return self.runs.record_workflow_run(*args, **kwargs)
 
-    def update_workflow_run(
-        self,
-        run_id: str,
-        *,
-        workspace_id: Optional[str] = None,
-        graph: Any = None,
-        patch: Optional[Dict[str, Any]] = None,
-        **fields: Any,
-    ) -> Dict[str, Any]:
-        """Patch a persisted workflow run in place for async execution."""
-        updates = {**(patch or {}), **fields}
-        state = self.load_state()
-        run = next((item for item in _listify(state.get("workflow_runs")) if item.get("id") == run_id), None)
-        if run is None or (workspace_id and self._record_workspace(run) != str(workspace_id)):
-            raise FileNotFoundError(run_id)
-        resolved_workspace = self._record_workspace(run)
-        old_timeline_len = len(run.get("timeline") or [])
-
-        for key, value in updates.items():
-            if value is None and key == "pause":
-                run.pop("pause", None)
-            else:
-                run[key] = value
-        status = str(run.get("status") or "")
-        run["updated_at"] = _now()
-        if status in RUN_TERMINAL_STATUSES:
-            run.setdefault("completed_at", _now())
-
-        workflow_id = run.get("workflow_id")
-        for wf in _listify(state.get("workflows")):
-            if wf.get("id") == workflow_id:
-                wf.setdefault("events", []).append({"type": "run_update", "timestamp": _now(), "payload": {"run_id": run_id, "status": status}})
-                wf["updated_at"] = _now()
-                break
-
-        if (
-            status in RUN_TERMINAL_STATUSES
-            and run.get("mode") != "simulation"
-            and graph is not None
-            and not run.get("graph_node_id")
-        ):
-            try:
-                ingested = graph.ingest_event(
-                    "WorkflowRun",
-                    f"{run.get('name')} {status}",
-                    user_email=run.get("user_email"),
-                    source="workspace_os",
-                    metadata={
-                        "run_id": run_id,
-                        "workflow_id": workflow_id,
-                        "status": status,
-                        "mode": run.get("mode"),
-                    },
-                )
-                run["graph_node_id"] = ingested.get("node_id")
-            except Exception as exc:
-                run["graph_error"] = str(exc)
+    def update_workflow_run(self, *args: Any, **kwargs: Any) -> Dict[str, Any]:
+        return self.runs.update_workflow_run(*args, **kwargs)
 
-        self.save_state(state)
-        run["contract"] = workflow_run_contract(run)
-        state = self.load_state()
-        for item in _listify(state.get("workflow_runs")):
-            if item.get("id") == run_id:
-                item["contract"] = run["contract"]
-                break
-        self.save_state(state)
+    def list_workflow_runs(self, *args: Any, **kwargs: Any) -> Dict[str, Any]:
+        return self.runs.list_workflow_runs(*args, **kwargs)
 
-        timeline = run.get("timeline") or []
-        if len(timeline) > old_timeline_len:
-            self._emit_replayable_timeline_events(
-                area="workflow",
-                run_id=run_id,
-                timeline=timeline[old_timeline_len:],
-                workspace_id=resolved_workspace,
-            )
-        if status == "failed":
-            self._emit_execution_event(area="workflow", event_type="execution_failed", payload={"run_id": run_id, "workflow_id": workflow_id, "status": status}, workspace_id=resolved_workspace)
-        elif status in {"ok", "partial"}:
-            self._emit_execution_event(area="workflow", event_type="workflow_completed", payload={"run_id": run_id, "workflow_id": workflow_id, "status": status}, workspace_id=resolved_workspace)
-        elif status == "cancelled":
-            self._emit_execution_event(area="workflow", event_type="execution_cancelled", payload={"run_id": run_id, "workflow_id": workflow_id, "status": status}, workspace_id=resolved_workspace)
-        elif status == "interrupted":
-            self._emit_execution_event(area="workflow", event_type="execution_interrupted", payload={"run_id": run_id, "workflow_id": workflow_id, "status": status}, workspace_id=resolved_workspace)
-        self.record_timeline_event("workflow", "workflow_run_update", {"run_id": run_id, "workflow_id": workflow_id, "status": status}, workspace_id=resolved_workspace)
-        return run
-
-    def list_workflow_runs(self, workflow_id: Optional[str] = None, limit: int = 50, workspace_id: Optional[str] = None) -> Dict[str, Any]:
-        runs = self._scoped(_listify(self.load_state().get("workflow_runs")), workspace_id)
-        if workflow_id:
-            runs = [run for run in runs if run.get("workflow_id") == workflow_id]
-        return {"runs": list(reversed(runs[-max(1, min(limit, 300)):]))}
-
-    def mark_workflow_run_resolved(
-        self, run_id: str, *, resumed_run_id: str, approved: bool,
-        workspace_id: Optional[str] = None,
-    ) -> Dict[str, Any]:
-        """Close out a paused run after its approval decision (one decision only)."""
-        state = self.load_state()
-        run = next((item for item in _listify(state.get("workflow_runs")) if item.get("id") == run_id), None)
-        if run is None or (workspace_id and self._record_workspace(run) != str(workspace_id)):
-            raise FileNotFoundError(run_id)
-        run["status"] = "resumed" if approved else "denied"
-        run["resolved_at"] = _now()
-        run["resumed_run_id"] = resumed_run_id
-        self.save_state(state)
-        return run
+    def mark_workflow_run_resolved(self, *args: Any, **kwargs: Any) -> Dict[str, Any]:
+        return self.runs.mark_workflow_run_resolved(*args, **kwargs)
+
+    def get_workflow_run(self, *args: Any, **kwargs: Any) -> Dict[str, Any]:
+        return self.runs.get_workflow_run(*args, **kwargs)
+
+    def reconcile_interrupted_runs(self, *args: Any, **kwargs: Any) -> Dict[str, Any]:
+        return self.runs.reconcile_interrupted_runs(*args, **kwargs)
 
-    def get_workflow_run(self, run_id: str, workspace_id: Optional[str] = None) -> Dict[str, Any]:
-        run = next((item for item in _listify(self.load_state().get("workflow_runs")) if item.get("id") == run_id), None)
-        if not run or (workspace_id and self._record_workspace(run) != str(workspace_id)):
-            raise FileNotFoundError(run_id)
-        return run
+    @staticmethod
+    def _replay_frames(run: Dict[str, Any], *, kind: str) -> List[Dict[str, Any]]:
+        return WorkspaceRuns._replay_frames(run, kind=kind)
+
+    def replay_agent_run(self, *args: Any, **kwargs: Any) -> Dict[str, Any]:
+        return self.runs.replay_agent_run(*args, **kwargs)
+
+    def replay_workflow_run(self, *args: Any, **kwargs: Any) -> Dict[str, Any]:
+        return self.runs.replay_workflow_run(*args, **kwargs)
+
+    def get_workflow(self, *args: Any, **kwargs: Any) -> Dict[str, Any]:
+        return self.runs.get_workflow(*args, **kwargs)
+
+    def update_workflow_definition(self, *args: Any, **kwargs: Any) -> Dict[str, Any]:
+        return self.runs.update_workflow_definition(*args, **kwargs)
+
+    def list_workflows(self, *args: Any, **kwargs: Any) -> Dict[str, Any]:
+        return self.runs.list_workflows(*args, **kwargs)
+
+    def record_workflow_event(self, *args: Any, **kwargs: Any) -> Dict[str, Any]:
+        return self.runs.record_workflow_event(*args, **kwargs)
 
     # ── review queue (5.6.0) ─────────────────────────────────────────────
     # Workspace-scoped suggestion inbox. Automation/trigger runs write drafts
@@ -1997,171 +1197,6 @@ class WorkspaceOSStore:
         )
         return item
 
-    def reconcile_interrupted_runs(self, *, reason: str = "server_startup") -> Dict[str, Any]:
-        """Mark durable active runs as interrupted after a process restart.
-
-        Queued/running/cancelling rows cannot have an owning asyncio task after
-        startup. Paused approval runs are intentionally left untouched so their
-        durable human decision cursor remains resumable.
-        """
-        state = self.load_state()
-        interrupted: List[Dict[str, Any]] = []
-        now = _now()
-        collections = (("agent_runs", "agent"), ("workflow_runs", "workflow"))
-        for key, area in collections:
-            for run in _listify(state.get(key)):
-                status = str(run.get("status") or "")
-                if status not in RUN_ACTIVE_STATUSES:
-                    continue
-                run["status"] = "interrupted"
-                run["interrupted_at"] = now
-                run["interrupt_reason"] = reason
-                run["updated_at"] = now
-                run.setdefault("timeline", []).append({
-                    "event": "execution_interrupted",
-                    "status": "interrupted",
-                    "reason": reason,
-                    "timestamp": now,
-                })
-                interrupted.append({
-                    "kind": area,
-                    "run_id": run.get("id"),
-                    "workspace_id": self._record_workspace(run),
-                    "previous_status": status,
-                })
-        if not interrupted:
-            return {"count": 0, "interrupted": []}
-        self.save_state(state)
-        for item in interrupted:
-            area = item["kind"]
-            run_id = item["run_id"]
-            workspace = item.get("workspace_id")
-            self._emit_execution_event(
-                area=area,
-                event_type="execution_interrupted",
-                payload={"run_id": run_id, "reason": reason, "previous_status": item.get("previous_status")},
-                workspace_id=workspace,
-            )
-        self.record_timeline_event(
-            "system",
-            "startup_reconciliation",
-            {"interrupted_runs": len(interrupted), "reason": reason},
-        )
-        return {"count": len(interrupted), "interrupted": interrupted}
-
-    @staticmethod
-    def _replay_frames(run: Dict[str, Any], *, kind: str) -> List[Dict[str, Any]]:
-        frames = []
-        for index, item in enumerate(run.get("timeline") or []):
-            event = item.get("event") or item.get("event_type") or item.get("type") or "event"
-            actor = (
-                item.get("agent_id")
-                or item.get("role")
-                or item.get("source_agent")
-                or item.get("target_agent")
-                or item.get("node")
-                or kind
-            )
-            result = item.get("result") if "result" in item else item.get("output")
-            decision = item.get("outcome") or item.get("verdict") or item.get("status")
-            frames.append({
-                "index": index,
-                "event": event,
-                "actor": actor,
-                "when": item.get("timestamp") or item.get("started_at") or run.get("created_at"),
-                "why": item.get("reason") or item.get("note") or item.get("name") or "",
-                "input": item.get("context_packet") or item.get("trigger") or run.get("input"),
-                "output": result,
-                "decision": decision,
-                "raw": item,
-            })
-        return frames
-
-    def replay_agent_run(self, run_id: str, workspace_id: Optional[str] = None) -> Dict[str, Any]:
-        run = self.get_agent_run(run_id, workspace_id=workspace_id)
-        return {
-            "kind": "agent",
-            "run_id": run_id,
-            "status": run.get("status"),
-            "workspace_id": self._record_workspace(run),
-            "contract": run.get("contract") or run_record_contract(run),
-            "replayable": True,
-            "frames": self._replay_frames(run, kind="agent"),
-            "handoffs": run.get("handoffs") or [],
-            "context_packets": run.get("context_packets") or [],
-            "review_history": run.get("review_history") or [],
-            "retry_history": run.get("retry_history") or [],
-        }
-
-    def replay_workflow_run(self, run_id: str, workspace_id: Optional[str] = None) -> Dict[str, Any]:
-        run = self.get_workflow_run(run_id, workspace_id=workspace_id)
-        return {
-            "kind": "workflow",
-            "run_id": run_id,
-            "status": run.get("status"),
-            "workspace_id": self._record_workspace(run),
-            "contract": run.get("contract") or workflow_run_contract(run),
-            "replayable": True,
-            "frames": self._replay_frames(run, kind="workflow"),
-            "outputs": run.get("outputs") or {},
-        }
-
-    def get_workflow(self, workflow_id: str, workspace_id: Optional[str] = None) -> Dict[str, Any]:
-        workflow = next((wf for wf in _listify(self.load_state().get("workflows")) if wf.get("id") == workflow_id), None)
-        if not workflow or (workspace_id and self._record_workspace(workflow) != str(workspace_id)):
-            raise FileNotFoundError(workflow_id)
-        return workflow
-
-    def update_workflow_definition(
-        self,
-        workflow_id: str,
-        *,
-        name: Optional[str] = None,
-        nodes: Optional[List[Dict[str, Any]]] = None,
-        metadata: Optional[Dict[str, Any]] = None,
-        workspace_id: Optional[str] = None,
-    ) -> Dict[str, Any]:
-        """Edit a stored workflow's node graph / name without losing its history."""
-        state = self.load_state()
-        workflow = next((wf for wf in _listify(state.get("workflows")) if wf.get("id") == workflow_id), None)
-        if not workflow or (workspace_id and self._record_workspace(workflow) != str(workspace_id)):
-            raise FileNotFoundError(workflow_id)
-        if name is not None and str(name).strip():
-            workflow["name"] = str(name).strip()
-        if nodes is not None:
-            workflow["nodes"] = nodes
-        if metadata is not None:
-            workflow["metadata"] = {**(workflow.get("metadata") or {}), **metadata}
-        workflow.setdefault("events", []).append({"type": "edited", "timestamp": _now()})
-        workflow["updated_at"] = _now()
-        self.save_state(state)
-        self.record_timeline_event("workflow", "workflow_edited", {"workflow_id": workflow_id})
-        return workflow
-
-    def list_workflows(self, query: str = "", workspace_id: Optional[str] = None) -> Dict[str, Any]:
-        workflows = list(reversed(self._scoped(_listify(self.load_state().get("workflows")), workspace_id)))
-        q = str(query or "").lower().strip()
-        if q:
-            workflows = [
-                wf for wf in workflows
-                if q in str(wf.get("name") or "").lower()
-                or q in json.dumps(wf.get("steps") or [], ensure_ascii=False).lower()
-            ]
-        return {"workflows": workflows}
-
-    def record_workflow_event(self, workflow_id: str, event_type: str, payload: Optional[Dict[str, Any]] = None) -> Dict[str, Any]:
-        state = self.load_state()
-        workflows = _listify(state.get("workflows"))
-        workflow = next((item for item in workflows if item.get("id") == workflow_id), None)
-        if not workflow:
-            raise FileNotFoundError(workflow_id)
-        event = {"type": event_type, "timestamp": _now(), "payload": payload or {}}
-        workflow.setdefault("events", []).append(event)
-        workflow["updated_at"] = _now()
-        self.save_state(state)
-        self.record_timeline_event("workflow", "workflow_event", {"workflow_id": workflow_id, "event_type": event_type})
-        return workflow
-
     # ------------------------------------------------------------------
     # Relationship explorer
     # ------------------------------------------------------------------
@@ -2284,144 +1319,33 @@ class WorkspaceOSStore:
     # Skills
     # ------------------------------------------------------------------
 
-    def list_skill_registry(self, skills_dir: Path, marketplace: Optional[List[Dict[str, Any]]] = None) -> Dict[str, Any]:
-        state = self.load_state()
-        registry = state.setdefault("skill_registry", {})
-        installed = []
-        if skills_dir.exists():
-            for skill_dir in sorted(skills_dir.iterdir()):
-                if not skill_dir.is_dir():
-                    continue
-                skill_md = skill_dir / "SKILL.md"
-                schema = skill_dir / "schema.json"
-                if not skill_md.exists():
-                    continue
-                desc = ""
-                try:
-                    for line in skill_md.read_text(encoding="utf-8").splitlines():
-                        if line.startswith("description:"):
-                            desc = line.split(":", 1)[1].strip()
-                            break
-                except Exception:
-                    desc = ""
-                version = "local"
-                if schema.exists():
-                    try:
-                        version = str((json.loads(schema.read_text(encoding="utf-8")) or {}).get("version") or "local")
-                    except Exception:
-                        version = "local"
-                entry = registry.setdefault(skill_dir.name, {})
-                entry.setdefault("enabled", True)
-                entry.update({
-                    "name": skill_dir.name,
-                    "description": desc,
-                    "version": version,
-                    "installed": True,
-                    "install_status": entry.get("install_status") or "ready",
-                    "validation_status": "ready" if skill_md.exists() else "missing_manifest",
-                    "source": entry.get("source") or "local",
-                    "path": str(skill_dir),
-                    "updated_at": entry.get("updated_at") or _now(),
-                })
-                installed.append(entry)
-        available = []
-        for item in marketplace or []:
-            name = item.get("skill") or item.get("name")
-            if not name:
-                continue
-            state_entry = registry.get(name, {})
-            available.append({
-                **item,
-                "enabled": bool(state_entry.get("enabled", True)),
-                "installed": bool(state_entry.get("installed")),
-                "install_status": state_entry.get("install_status") or ("ready" if state_entry.get("installed") else "available"),
-                "validation_status": state_entry.get("validation_status") or item.get("validation_status") or ("ready" if state_entry.get("installed") else "not_installed"),
-                "source": state_entry.get("source") or item.get("source") or item.get("plugin") or "marketplace",
-                "version": state_entry.get("version") or item.get("version") or "remote",
-            })
-        self.save_state(state)
-        return {
-            "installed": installed,
-            "available": available,
-            "registry": registry,
-            "total_installed": len(installed),
-            "total_available": len(available),
-        }
+    def list_skill_registry(self, *args: Any, **kwargs: Any) -> Dict[str, Any]:
+        return self.skills.list_skill_registry(*args, **kwargs)
 
-    def set_skill_enabled(self, skill: str, enabled: bool) -> Dict[str, Any]:
-        state = self.load_state()
-        entry = state.setdefault("skill_registry", {}).setdefault(skill, {"name": skill})
-        entry["enabled"] = bool(enabled)
-        entry["updated_at"] = _now()
-        self.save_state(state)
-        self.record_timeline_event("skills", "skill_enabled" if enabled else "skill_disabled", {"skill": skill})
-        return entry
+    def set_skill_enabled(self, *args: Any, **kwargs: Any) -> Dict[str, Any]:
+        return self.skills.set_skill_enabled(*args, **kwargs)
 
-    def mark_skill_installed(self, skill: str, *, version: str = "local", metadata: Optional[Dict[str, Any]] = None) -> Dict[str, Any]:
-        state = self.load_state()
-        entry = state.setdefault("skill_registry", {}).setdefault(skill, {"name": skill})
-        entry.update({
-            "installed": True,
-            "enabled": entry.get("enabled", True),
-            "version": version,
-            "install_status": "ready",
-            "validation_status": "ready",
-            "source": (metadata or {}).get("source") or entry.get("source") or "marketplace",
-            "metadata": metadata or entry.get("metadata") or {},
-            "updated_at": _now(),
-        })
-        self.save_state(state)
-        self.record_timeline_event("skills", "skill_installed", {"skill": skill, "version": version})
-        return entry
+    def mark_skill_installed(self, *args: Any, **kwargs: Any) -> Dict[str, Any]:
+        return self.skills.mark_skill_installed(*args, **kwargs)
 
-    def mark_skill_uninstalled(self, skill: str) -> Dict[str, Any]:
-        state = self.load_state()
-        entry = state.setdefault("skill_registry", {}).setdefault(skill, {"name": skill})
-        entry.update({"installed": False, "enabled": False, "updated_at": _now()})
-        self.save_state(state)
-        self.record_timeline_event("skills", "skill_uninstalled", {"skill": skill})
-        return entry
+    def mark_skill_uninstalled(self, *args: Any, **kwargs: Any) -> Dict[str, Any]:
+        return self.skills.mark_skill_uninstalled(*args, **kwargs)
 
     # ------------------------------------------------------------------
     # Plugin SDK registry — mirrors the skill registry contract.
     # ------------------------------------------------------------------
 
     def list_plugin_registry(self) -> Dict[str, Any]:
-        return dict(self.load_state().get("plugin_registry") or {})
+        return self.plugins.list_plugin_registry()
 
     def set_plugin_enabled(self, plugin_id: str, enabled: bool) -> Dict[str, Any]:
-        state = self.load_state()
-        entry = state.setdefault("plugin_registry", {}).setdefault(plugin_id, {"id": plugin_id})
-        entry["enabled"] = bool(enabled)
-        entry["updated_at"] = _now()
-        self.save_state(state)
-        self.record_timeline_event("plugins", "plugin_enabled" if enabled else "plugin_disabled", {"plugin": plugin_id})
-        return entry
+        return self.plugins.set_plugin_enabled(plugin_id, enabled)
 
     def mark_plugin_installed(self, plugin_id: str, *, version: str = "0.0.0", metadata: Optional[Dict[str, Any]] = None) -> Dict[str, Any]:
-        state = self.load_state()
-        entry = state.setdefault("plugin_registry", {}).setdefault(plugin_id, {"id": plugin_id})
-        entry.update({
-            "id": plugin_id,
-            "installed": True,
-            "enabled": entry.get("enabled", True),
-            "version": version,
-            "install_status": "ready",
-            "validation_status": "valid",
-            "metadata": metadata or entry.get("metadata") or {},
-            "updated_at": _now(),
-        })
-        self.save_state(state)
-        self.record_timeline_event("plugins", "plugin_installed", {"plugin": plugin_id, "version": version})
-        return entry
+        return self.plugins.mark_plugin_installed(plugin_id, version=version, metadata=metadata)
 
     def mark_plugin_uninstalled(self, plugin_id: str) -> Dict[str, Any]:
-        state = self.load_state()
-        entry = state.setdefault("plugin_registry", {}).setdefault(plugin_id, {"id": plugin_id})
-        entry.update({"installed": False, "enabled": False, "updated_at": _now()})
-        self.save_state(state)
-        self.record_timeline_event("plugins", "plugin_uninstalled", {"plugin": plugin_id})
-        return {"status": "ok", "plugin_id": plugin_id, "registry": entry}
+        return self.plugins.mark_plugin_uninstalled(plugin_id)
 
     # ------------------------------------------------------------------
     # Marketplace template registry (v2.1 foundation)
@@ -2433,16 +1357,7 @@ class WorkspaceOSStore:
         return base if workspace_id == DEFAULT_WORKSPACE_ID else f"{workspace_id}:{base}"
 
     def list_template_registry(self, workspace_id: Optional[str] = None) -> Dict[str, Any]:
-        state = self.load_state()
-        registry = dict(state.get("template_registry") or {})
-        if workspace_id is None:
-            return registry
-        scope = self._resolve_scope(workspace_id, state)
-        return {
-            key: value
-            for key, value in registry.items()
-            if self._record_workspace(value) == scope
-        }
+        return self.plugins.list_template_registry(workspace_id)
 
     def mark_template_installed(
         self,
@@ -2453,22 +1368,7 @@ class WorkspaceOSStore:
         metadata: Optional[Dict[str, Any]] = None,
         workspace_id: Optional[str] = None,
     ) -> Dict[str, Any]:
-        state = self.load_state()
-        scope = self._resolve_scope(workspace_id, state)
-        key = self._template_registry_key(kind, template_id, scope)
-        entry = state.setdefault("template_registry", {}).setdefault(key, {"id": template_id, "kind": kind})
-        entry.update({
-            "id": template_id,
-            "kind": kind,
-            "version": version,
-            "installed": True,
-            "workspace_id": scope,
-            "metadata": metadata or entry.get("metadata") or {},
-            "updated_at": _now(),
-        })
-        self.save_state(state)
-        self.record_timeline_event("marketplace", "template_installed", {"kind": kind, "template_id": template_id}, workspace_id=scope)
-        return entry
+        return self.plugins.mark_template_installed(kind=kind, template_id=template_id, version=version, metadata=metadata, workspace_id=workspace_id)
 
     # ------------------------------------------------------------------
     # Audit timeline
@@ -2485,55 +1385,7 @@ class WorkspaceOSStore:
         until: Optional[str] = None,
         limit: int = 100,
     ) -> Dict[str, Any]:
-        since_dt = _parse_iso(since)
-        until_dt = _parse_iso(until)
-        filtered = []
-        for event in audit_events:
-            stamp = _parse_iso(event.get("timestamp"))
-            if user and user.lower() not in str(event.get("user_email") or event.get("user") or "").lower():
-                continue
-            if event_type and event_type.lower() not in str(event.get("event_type") or "").lower():
-                continue
-            if model and model.lower() not in json.dumps(event, ensure_ascii=False).lower():
-                continue
-            if since_dt and stamp and stamp < since_dt:
-                continue
-            if until_dt and stamp and stamp > until_dt:
-                continue
-            filtered.append({
-                **event,
-                "category": self._audit_category(event),
-            })
-        filtered.sort(key=lambda item: item.get("timestamp") or "", reverse=True)
-        return {"events": filtered[: max(1, min(limit, 1000))], "total": len(filtered)}
+        return self._timeline.filter_audit_timeline(audit_events, user=user, event_type=event_type, model=model, since=since, until=until, limit=limit)
 
-    @staticmethod
-    def _audit_category(event: Dict[str, Any]) -> str:
-        raw = str(event.get("event_type") or "").lower()
-        if "model" in raw or "chat" in raw:
-            return "model_usage"
-        if "file" in raw or "document" in raw or "local" in raw:
-            return "file_access"
-        if "folder" in raw or "permission" in raw:
-            return "folder_approval"
-        if "sensitive" in raw or "secret" in raw:
-            return "sensitive_data"
-        if "admin" in raw or "user" in raw or "sso" in raw:
-            return "admin_action"
-        if "security" in raw or "auth" in raw or "login" in raw:
-            return "security_event"
-        return "workspace_event"
-
-
-def remove_skill_directory(skills_dir: Path, skill: str) -> Dict[str, Any]:
-    """Remove an installed skill directory after caller has performed auth checks."""
-
-    safe_name = _safe_slug(skill)
-    target = (skills_dir / safe_name).resolve()
-    root = skills_dir.resolve()
-    if not str(target).startswith(str(root)):
-        raise ValueError("invalid skill path")
-    if not target.exists() or not target.is_dir():
-        raise FileNotFoundError(skill)
-    shutil.rmtree(target)
-    return {"status": "ok", "skill": safe_name, "removed_path": str(target)}
+    def timeline(self, audit_events: Optional[Iterable[Dict[str, Any]]] = None, limit: int = 100, workspace_id: Optional[str] = None) -> Dict[str, Any]:
+        return self._timeline.timeline(audit_events=audit_events, limit=limit, workspace_id=workspace_id)