shellbrain 0.1.0__py3-none-any.whl

app/periphery/telemetry/session_selection.py

@@ -0,0 +1,156 @@
+"""Helpers for resolving low-overhead telemetry session-selection summaries."""
+
+from __future__ import annotations
+
+from dataclasses import dataclass, replace
+from datetime import datetime, timezone
+import json
+from pathlib import Path
+from typing import Any
+
+from app.core.entities.telemetry import SessionSelectionSummary
+from app.periphery.episodes.claude_code import list_claude_code_sessions_for_repo
+from app.periphery.episodes.codex import list_codex_sessions_for_repo
+from app.periphery.episodes.source_discovery import SUPPORTED_HOSTS, default_search_roots
+
+
+@dataclass(frozen=True)
+class EventsDiscoveryCandidate:
+    """Concrete host-session discovery result used by the events path."""
+
+    host_app: str
+    host_session_key: str
+    transcript_path: Path
+    search_roots: list[Path]
+    summary: SessionSelectionSummary
+
+
+def discover_events_candidate(
+    *,
+    repo_root: Path,
+    search_roots_by_host: dict[str, list[Path]] | None = None,
+) -> EventsDiscoveryCandidate | None:
+    """Resolve the newest repo-matching host session across supported hosts."""
+
+    discovered: list[tuple[str, dict[str, Any], list[Path]]] = []
+    for host_app in SUPPORTED_HOSTS:
+        search_roots = _search_roots_for_host(
+            repo_root=repo_root,
+            host_app=host_app,
+            search_roots_by_host=search_roots_by_host,
+        )
+        candidates = _list_candidates_for_host(
+            host_app=host_app,
+            repo_root=repo_root,
+            search_roots=search_roots,
+        )
+        for candidate in candidates:
+            discovered.append((host_app, candidate, search_roots))
+
+    if not discovered:
+        return None
+
+    host_app, candidate, search_roots = max(
+        discovered,
+        key=lambda item: (float(item[1]["updated_at"]), item[0]),
+    )
+    host_session_key = str(candidate["host_session_key"])
+    summary = SessionSelectionSummary(
+        selected_host_app=host_app,
+        selected_host_session_key=host_session_key,
+        selected_thread_id=f"{host_app}:{host_session_key}",
+        matching_candidate_count=len(discovered),
+        selection_ambiguous=len(discovered) > 1,
+    )
+    return EventsDiscoveryCandidate(
+        host_app=host_app,
+        host_session_key=host_session_key,
+        transcript_path=Path(str(candidate["transcript_path"])),
+        search_roots=search_roots,
+        summary=summary,
+    )
+
+
+def read_runtime_session_status(repo_root: Path) -> dict[str, Any] | None:
+    """Read the repo-local poller status file when it exists and is valid JSON."""
+
+    status_path = repo_root / ".shellbrain" / "episode_sync_status.json"
+    try:
+        payload = json.loads(status_path.read_text(encoding="utf-8"))
+    except (FileNotFoundError, json.JSONDecodeError):
+        return None
+    return payload if isinstance(payload, dict) else None
+
+
+def summarize_runtime_selection(*, repo_root: Path, repo_id: str, uow=None) -> SessionSelectionSummary:
+    """Resolve lightweight session context from the repo-local poller status file."""
+
+    status = read_runtime_session_status(repo_root)
+    if status is None:
+        return SessionSelectionSummary()
+
+    hosts = status.get("hosts")
+    if not isinstance(hosts, dict):
+        return SessionSelectionSummary()
+
+    candidates: list[tuple[str, str, datetime]] = []
+    for host_app, raw_host_status in hosts.items():
+        if not isinstance(raw_host_status, dict):
+            continue
+        session_key = raw_host_status.get("current_session_key")
+        if not isinstance(session_key, str) or not session_key:
+            continue
+        candidates.append((host_app, session_key, _parse_status_time(raw_host_status.get("last_successful_sync_at"))))
+
+    if not candidates:
+        return SessionSelectionSummary()
+
+    host_app, session_key, _ = max(candidates, key=lambda item: (item[2], item[0]))
+    summary = SessionSelectionSummary(
+        selected_host_app=host_app,
+        selected_host_session_key=session_key,
+        selected_thread_id=f"{host_app}:{session_key}",
+        matching_candidate_count=len(candidates),
+        selection_ambiguous=len(candidates) > 1,
+    )
+    if uow is None:
+        return summary
+
+    episode = uow.episodes.get_episode_by_thread(repo_id=repo_id, thread_id=summary.selected_thread_id)
+    if episode is None:
+        return summary
+    return replace(summary, selected_episode_id=episode.id)
+
+
+def _search_roots_for_host(
+    *,
+    repo_root: Path,
+    host_app: str,
+    search_roots_by_host: dict[str, list[Path]] | None,
+) -> list[Path]:
+    """Resolve bounded search roots for one host with optional test overrides."""
+
+    if search_roots_by_host is not None:
+        return [Path(path) for path in search_roots_by_host.get(host_app, [])]
+    return default_search_roots(repo_root=repo_root, host_app=host_app)
+
+
+def _list_candidates_for_host(*, host_app: str, repo_root: Path, search_roots: list[Path]) -> list[dict[str, Any]]:
+    """List all repo-matching host sessions for one supported host."""
+
+    if host_app == "codex":
+        return list_codex_sessions_for_repo(repo_root=repo_root, search_roots=search_roots)
+    if host_app == "claude_code":
+        return list_claude_code_sessions_for_repo(repo_root=repo_root, search_roots=search_roots)
+    raise ValueError(f"Unsupported host app for telemetry discovery: {host_app}")
+
+
+def _parse_status_time(value: object) -> datetime:
+    """Parse one poller status timestamp or return the minimum UTC instant."""
+
+    if not isinstance(value, str) or not value:
+        return datetime.min.replace(tzinfo=timezone.utc)
+    try:
+        return datetime.fromisoformat(value.replace("Z", "+00:00"))
+    except ValueError:
+        return datetime.min.replace(tzinfo=timezone.utc)

app/periphery/telemetry/sync_summary.py

@@ -0,0 +1,65 @@
+"""Helpers for assembling episode-sync telemetry rows."""
+
+from __future__ import annotations
+
+from datetime import datetime, timezone
+
+from app.core.entities.telemetry import EpisodeSyncRunRecord, EpisodeSyncToolTypeRecord
+
+
+def build_episode_sync_records(
+    *,
+    sync_run_id: str,
+    source: str,
+    invocation_id: str | None,
+    repo_id: str,
+    host_app: str,
+    host_session_key: str,
+    thread_id: str,
+    episode_id: str | None,
+    transcript_path: str | None,
+    outcome: str,
+    error_stage: str | None,
+    error_message: str | None,
+    duration_ms: int,
+    imported_event_count: int,
+    total_event_count: int,
+    user_event_count: int,
+    assistant_event_count: int,
+    tool_event_count: int,
+    system_event_count: int,
+    tool_type_counts: dict[str, int] | None,
+) -> tuple[EpisodeSyncRunRecord, list[EpisodeSyncToolTypeRecord]]:
+    """Build one sync-run record plus sorted per-tool aggregate rows."""
+
+    run = EpisodeSyncRunRecord(
+        id=sync_run_id,
+        source=source,
+        invocation_id=invocation_id,
+        repo_id=repo_id,
+        host_app=host_app,
+        host_session_key=host_session_key,
+        thread_id=thread_id,
+        episode_id=episode_id,
+        transcript_path=transcript_path,
+        outcome=outcome,
+        error_stage=error_stage,
+        error_message=error_message,
+        duration_ms=duration_ms,
+        imported_event_count=imported_event_count,
+        total_event_count=total_event_count,
+        user_event_count=user_event_count,
+        assistant_event_count=assistant_event_count,
+        tool_event_count=tool_event_count,
+        system_event_count=system_event_count,
+        created_at=datetime.now(timezone.utc),
+    )
+    tool_type_rows = [
+        EpisodeSyncToolTypeRecord(
+            sync_run_id=sync_run_id,
+            tool_type=tool_type,
+            event_count=count,
+        )
+        for tool_type, count in sorted((tool_type_counts or {}).items())
+    ]
+    return run, tool_type_rows

app/periphery/validation/__init__.py

@@ -0,0 +1 @@
+"""Periphery-level request validation helpers."""

app/periphery/validation/integrity_validation.py

@@ -0,0 +1,253 @@
+"""Database-integrity compatibility checks for validated edge requests."""
+
+from app.core.contracts.errors import ErrorCode, ErrorDetail
+from app.core.contracts.requests import (
+    AssociationLinkUpdate,
+    FactUpdateLinkUpdate,
+    MemoryBatchUpdateRequest,
+    MemoryCreateAssociationLink,
+    MemoryCreateRequest,
+    MemoryUpdateRequest,
+    UtilityVoteUpdate,
+)
+from app.core.entities.memory import Memory, MemoryKind, MemoryScope
+from app.core.interfaces.unit_of_work import IUnitOfWork
+
+
+def _is_visible(memory: Memory, repo_id: str) -> bool:
+    """Determine whether a memory is visible inside a repo operation context."""
+
+    return memory.repo_id == repo_id or memory.scope == MemoryScope.GLOBAL
+
+
+def _require_memory(uow: IUnitOfWork, *, memory_id: str, field: str) -> tuple[Memory | None, list[ErrorDetail]]:
+    """Fetch a memory row and return a not-found contract error when missing."""
+
+    memory = uow.memories.get(memory_id)
+    if memory is None:
+        return None, [ErrorDetail(code=ErrorCode.NOT_FOUND, message=f"Memory not found: {memory_id}", field=field)]
+    return memory, []
+
+
+def _validate_evidence_refs(
+    uow: IUnitOfWork,
+    *,
+    repo_id: str,
+    refs: list[str],
+    field_prefix: str,
+) -> list[ErrorDetail]:
+    """Validate that evidence refs resolve to repo-visible episode events."""
+
+    if not refs:
+        return []
+
+    existing_ids = set(uow.episodes.list_existing_event_ids(event_ids=refs))
+    visible_ids = set(uow.episodes.list_visible_event_ids(repo_id=repo_id, event_ids=refs))
+    errors: list[ErrorDetail] = []
+
+    for index, ref in enumerate(refs):
+        field = f"{field_prefix}.{index}"
+        if ref not in existing_ids:
+            errors.append(
+                ErrorDetail(
+                    code=ErrorCode.NOT_FOUND,
+                    message=f"Episode event not found: {ref}",
+                    field=field,
+                )
+            )
+            continue
+        if ref not in visible_ids:
+            errors.append(
+                ErrorDetail(
+                    code=ErrorCode.INTEGRITY_ERROR,
+                    message="Referenced episode event is not visible for this repo_id",
+                    field=field,
+                )
+            )
+    return errors
+
+
+def validate_create_integrity(request: MemoryCreateRequest, uow: IUnitOfWork) -> list[ErrorDetail]:
+    """Validate database integrity constraints for create operations."""
+
+    errors = _validate_evidence_refs(
+        uow,
+        repo_id=request.repo_id,
+        refs=list(request.memory.evidence_refs),
+        field_prefix="memory.evidence_refs",
+    )
+    links = request.memory.links
+    if links.problem_id:
+        problem_memory, problem_errors = _require_memory(uow, memory_id=links.problem_id, field="memory.links.problem_id")
+        errors.extend(problem_errors)
+        if problem_memory and not _is_visible(problem_memory, request.repo_id):
+            errors.append(
+                ErrorDetail(
+                    code=ErrorCode.INTEGRITY_ERROR,
+                    message="Referenced problem memory is not visible for this repo_id",
+                    field="memory.links.problem_id",
+                )
+            )
+        if problem_memory and problem_memory.kind != MemoryKind.PROBLEM:
+            errors.append(
+                ErrorDetail(
+                    code=ErrorCode.INTEGRITY_ERROR,
+                    message="Referenced problem_id must point to a problem memory",
+                    field="memory.links.problem_id",
+                )
+            )
+
+    for index, association in enumerate(links.associations):
+        target, target_errors = _require_memory(
+            uow,
+            memory_id=association.to_memory_id,
+            field=f"memory.links.associations.{index}.to_memory_id",
+        )
+        errors.extend(target_errors)
+        if target and not _is_visible(target, request.repo_id):
+            errors.append(
+                ErrorDetail(
+                    code=ErrorCode.INTEGRITY_ERROR,
+                    message="Association target shellbrain is not visible for this repo_id",
+                    field=f"memory.links.associations.{index}.to_memory_id",
+                )
+            )
+    return errors
+
+
+def validate_update_integrity(request: MemoryUpdateRequest | MemoryBatchUpdateRequest, uow: IUnitOfWork) -> list[ErrorDetail]:
+    """Validate database integrity constraints for update operations."""
+
+    if isinstance(request, MemoryBatchUpdateRequest):
+        errors: list[ErrorDetail] = []
+        for index, item in enumerate(request.updates):
+            single_errors = validate_update_integrity(
+                MemoryUpdateRequest(
+                    repo_id=request.repo_id,
+                    memory_id=item.memory_id,
+                    update=item.update,
+                ),
+                uow,
+            )
+            for error in single_errors:
+                field = error.field
+                if field is not None:
+                    field = f"updates.{index}.{field}"
+                errors.append(ErrorDetail(code=error.code, message=error.message, field=field))
+        return errors
+
+    errors: list[ErrorDetail] = []
+    target_memory, target_errors = _require_memory(uow, memory_id=request.memory_id, field="memory_id")
+    errors.extend(target_errors)
+    if target_memory and not _is_visible(target_memory, request.repo_id):
+        errors.append(
+            ErrorDetail(
+                code=ErrorCode.INTEGRITY_ERROR,
+                message="Target memory is not visible for this repo_id",
+                field="memory_id",
+            )
+        )
+
+    update = request.update
+    if isinstance(update, UtilityVoteUpdate):
+        errors.extend(
+            _validate_evidence_refs(
+                uow,
+                repo_id=request.repo_id,
+                refs=list(update.evidence_refs),
+                field_prefix="update.evidence_refs",
+            )
+        )
+        problem_memory, problem_errors = _require_memory(uow, memory_id=update.problem_id, field="update.problem_id")
+        errors.extend(problem_errors)
+        if problem_memory and not _is_visible(problem_memory, request.repo_id):
+            errors.append(
+                ErrorDetail(
+                    code=ErrorCode.INTEGRITY_ERROR,
+                    message="utility_vote.problem_id is not visible for this repo_id",
+                    field="update.problem_id",
+                )
+            )
+        if problem_memory and problem_memory.kind != MemoryKind.PROBLEM:
+            errors.append(
+                ErrorDetail(
+                    code=ErrorCode.INTEGRITY_ERROR,
+                    message="utility_vote.problem_id must reference a problem memory",
+                    field="update.problem_id",
+                )
+            )
+
+    if isinstance(update, FactUpdateLinkUpdate):
+        errors.extend(
+            _validate_evidence_refs(
+                uow,
+                repo_id=request.repo_id,
+                refs=list(update.evidence_refs),
+                field_prefix="update.evidence_refs",
+            )
+        )
+        old_fact, old_errors = _require_memory(uow, memory_id=update.old_fact_id, field="update.old_fact_id")
+        new_fact, new_errors = _require_memory(uow, memory_id=update.new_fact_id, field="update.new_fact_id")
+        errors.extend(old_errors)
+        errors.extend(new_errors)
+        if old_fact and not _is_visible(old_fact, request.repo_id):
+            errors.append(
+                ErrorDetail(
+                    code=ErrorCode.INTEGRITY_ERROR,
+                    message="old_fact_id is not visible for this repo_id",
+                    field="update.old_fact_id",
+                )
+            )
+        if old_fact and old_fact.kind != MemoryKind.FACT:
+            errors.append(
+                ErrorDetail(
+                    code=ErrorCode.INTEGRITY_ERROR,
+                    message="old_fact_id must reference a fact memory",
+                    field="update.old_fact_id",
+                )
+            )
+        if new_fact and not _is_visible(new_fact, request.repo_id):
+            errors.append(
+                ErrorDetail(
+                    code=ErrorCode.INTEGRITY_ERROR,
+                    message="new_fact_id is not visible for this repo_id",
+                    field="update.new_fact_id",
+                )
+            )
+        if new_fact and new_fact.kind != MemoryKind.FACT:
+            errors.append(
+                ErrorDetail(
+                    code=ErrorCode.INTEGRITY_ERROR,
+                    message="new_fact_id must reference a fact memory",
+                    field="update.new_fact_id",
+                )
+            )
+        if target_memory and target_memory.kind != MemoryKind.CHANGE:
+            errors.append(
+                ErrorDetail(
+                    code=ErrorCode.INTEGRITY_ERROR,
+                    message="memory_id must reference a change memory for fact_update_link",
+                    field="memory_id",
+                )
+            )
+
+    if isinstance(update, AssociationLinkUpdate):
+        errors.extend(
+            _validate_evidence_refs(
+                uow,
+                repo_id=request.repo_id,
+                refs=list(update.evidence_refs),
+                field_prefix="update.evidence_refs",
+            )
+        )
+        target, target_errors = _require_memory(uow, memory_id=update.to_memory_id, field="update.to_memory_id")
+        errors.extend(target_errors)
+        if target and not _is_visible(target, request.repo_id):
+            errors.append(
+                ErrorDetail(
+                    code=ErrorCode.INTEGRITY_ERROR,
+                    message="association_link.to_memory_id is not visible for this repo_id",
+                    field="update.to_memory_id",
+                )
+            )
+    return errors

app/periphery/validation/semantic_validation.py

@@ -0,0 +1,94 @@
+"""Semantic validation checks for operation requests at the system edge."""
+
+from app.core.contracts.errors import ErrorCode, ErrorDetail
+from app.core.contracts.requests import (
+    AssociationLinkUpdate,
+    FactUpdateLinkUpdate,
+    MemoryBatchUpdateRequest,
+    MemoryCreateRequest,
+    MemoryUpdateRequest,
+)
+from app.core.entities.memory import MemoryKind
+
+
+def validate_create_semantics(request: MemoryCreateRequest) -> list[ErrorDetail]:
+    """Validate semantic constraints for create operations."""
+
+    errors: list[ErrorDetail] = []
+    kind = MemoryKind(request.memory.kind)
+    problem_id = request.memory.links.problem_id
+    if kind in {MemoryKind.SOLUTION, MemoryKind.FAILED_TACTIC} and not problem_id:
+        errors.append(
+            ErrorDetail(
+                code=ErrorCode.SEMANTIC_ERROR,
+                message="links.problem_id is required for solution and failed_tactic memories",
+                field="memory.links.problem_id",
+            )
+        )
+    if kind in {MemoryKind.PROBLEM, MemoryKind.FACT, MemoryKind.PREFERENCE, MemoryKind.CHANGE} and problem_id:
+        errors.append(
+            ErrorDetail(
+                code=ErrorCode.SEMANTIC_ERROR,
+                message="links.problem_id is only valid for solution and failed_tactic memories",
+                field="memory.links.problem_id",
+            )
+        )
+
+    seen_pairs: set[tuple[str, str]] = set()
+    for index, association in enumerate(request.memory.links.associations):
+        pair = (association.to_memory_id, association.relation_type)
+        if pair in seen_pairs:
+            errors.append(
+                ErrorDetail(
+                    code=ErrorCode.SEMANTIC_ERROR,
+                    message="Duplicate association link entries are not allowed",
+                    field=f"memory.links.associations.{index}",
+                )
+            )
+        seen_pairs.add(pair)
+    return errors
+
+
+def validate_update_semantics(request: MemoryUpdateRequest | MemoryBatchUpdateRequest) -> list[ErrorDetail]:
+    """Validate semantic constraints for update operations."""
+
+    errors: list[ErrorDetail] = []
+    if isinstance(request, MemoryBatchUpdateRequest):
+        problem_ids = {item.update.problem_id for item in request.updates}
+        if len(problem_ids) > 1:
+            errors.append(
+                ErrorDetail(
+                    code=ErrorCode.SEMANTIC_ERROR,
+                    message="Batch utility votes must share the same problem_id",
+                    field="updates",
+                )
+            )
+        return errors
+
+    update = request.update
+    if isinstance(update, AssociationLinkUpdate) and update.to_memory_id == request.memory_id:
+        errors.append(
+            ErrorDetail(
+                code=ErrorCode.SEMANTIC_ERROR,
+                message="association links cannot self-reference the source memory",
+                field="update.to_memory_id",
+            )
+        )
+    if isinstance(update, FactUpdateLinkUpdate):
+        if update.old_fact_id == update.new_fact_id:
+            errors.append(
+                ErrorDetail(
+                    code=ErrorCode.SEMANTIC_ERROR,
+                    message="fact_update_link requires different old_fact_id and new_fact_id values",
+                    field="update.new_fact_id",
+                )
+            )
+        if update.old_fact_id == request.memory_id or update.new_fact_id == request.memory_id:
+            errors.append(
+                ErrorDetail(
+                    code=ErrorCode.SEMANTIC_ERROR,
+                    message="memory_id is the change shellbrain id and cannot equal old_fact_id/new_fact_id",
+                    field="memory_id",
+                )
+            )
+    return errors