feat: add scenario records

Author: cucupac

README.md

@@ -80,7 +80,7 @@ Use Shellbrain Session Start in your agent of choice. Then, just work normally.
 
 **Claude Code:** *Use `/shellbrain-session-start` to get up to speed in this repo and record durable evidence-backed learnings.*
 
-**Codex:** *Use `$shellbrain-session-start` to get up to speed in this repo and record durable evidence-backed learnings.*
+**Codex:** *Use $shellbrain-session-start to get up to speed in this repo and record durable evidence-backed learnings.*
 
 **Cursor:** *Use `/shellbrain-session-start` to get up to speed in this repo and record durable evidence-backed learnings.*
 

app/core/entities/scenarios.py

@@ -0,0 +1,67 @@
+"""Scenario entities for bounded problem-solving run windows."""
+
+from __future__ import annotations
+
+from dataclasses import dataclass
+from datetime import datetime
+from enum import Enum
+
+
+class ScenarioOutcome(str, Enum):
+    """Agent-facing terminal outcomes for one problem-solving scenario."""
+
+    SOLVED = "solved"
+    ABANDONED = "abandoned"
+
+
+class ProblemRunStatus(str, Enum):
+    """Durable storage statuses for explicit problem-run windows."""
+
+    OPEN = "open"
+    CLOSED = "closed"
+    ABANDONED = "abandoned"
+
+
+@dataclass(frozen=True, kw_only=True)
+class ProblemRun:
+    """One bounded problem-solving scenario stored for token/ROI analysis."""
+
+    id: str
+    repo_id: str
+    status: ProblemRunStatus
+    opened_at: datetime
+    opened_by: str
+    thread_id: str | None = None
+    host_app: str | None = None
+    host_session_key: str | None = None
+    episode_id: str | None = None
+    opened_event_id: str | None = None
+    closed_at: datetime | None = None
+    closed_by: str | None = None
+    closed_event_id: str | None = None
+    problem_memory_id: str | None = None
+    solution_memory_id: str | None = None
+    created_at: datetime | None = None
+    updated_at: datetime | None = None
+
+    def __post_init__(self) -> None:
+        """Keep invalid run windows from crossing core boundaries."""
+
+        for field_name in ("id", "repo_id", "opened_by"):
+            value = getattr(self, field_name)
+            if not isinstance(value, str) or not value.strip():
+                raise ValueError(f"{field_name} must be a non-empty string")
+        if self.status == ProblemRunStatus.OPEN and self.closed_at is not None:
+            raise ValueError("open problem runs cannot have closed_at")
+        if self.status != ProblemRunStatus.OPEN and self.closed_at is None:
+            raise ValueError("closed problem runs require closed_at")
+        if self.closed_at is not None and self.closed_at < self.opened_at:
+            raise ValueError("closed_at must be greater than or equal to opened_at")
+
+
+def outcome_to_problem_run_status(outcome: ScenarioOutcome) -> ProblemRunStatus:
+    """Map the agent-facing scenario outcome to durable run status."""
+
+    if outcome == ScenarioOutcome.SOLVED:
+        return ProblemRunStatus.CLOSED
+    return ProblemRunStatus.ABANDONED

app/core/ports/db/episode_repositories.py

@@ -40,6 +40,16 @@ def get_episode(
     ) -> Episode | None:
         """This method fetches one repo-visible episode by id."""
 
+    @abstractmethod
+    def get_event(
+        self,
+        *,
+        repo_id: str,
+        episode_id: str,
+        event_id: str,
+    ) -> EpisodeEvent | None:
+        """This method fetches one repo-visible event by id inside an episode."""
+
     @abstractmethod
     def list_event_keys(self, *, episode_id: str) -> Sequence[str]:
         """This method returns already-imported upstream event keys for one episode."""

app/core/ports/db/problem_runs.py

@@ -0,0 +1,26 @@
+"""Repository ports for explicit problem-run scenario windows."""
+
+from __future__ import annotations
+
+from abc import ABC, abstractmethod
+
+from app.core.entities.scenarios import ProblemRun
+
+
+class IProblemRunsRepo(ABC):
+    """Persistence behavior for bounded problem-solving scenario records."""
+
+    @abstractmethod
+    def get_by_scenario_key(
+        self,
+        *,
+        repo_id: str,
+        episode_id: str,
+        problem_memory_id: str,
+        opened_event_id: str,
+    ) -> ProblemRun | None:
+        """Return the existing scenario row for one natural idempotency key."""
+
+    @abstractmethod
+    def add(self, run: ProblemRun) -> None:
+        """Append one explicit problem-run scenario window."""

app/core/ports/db/unit_of_work.py

@@ -14,6 +14,7 @@
     IMemoriesRepo,
     IUtilityRepo,
 )
+from app.core.ports.db.problem_runs import IProblemRunsRepo
 from app.core.ports.embeddings.retrieval import IVectorSearch
 from app.core.ports.db.retrieval_repositories import (
     IKeywordRetrievalRepo,
@@ -37,6 +38,7 @@ class IUnitOfWork(ABC):
     read_policy: IReadPolicyRepo
     guidance: IPendingUtilityCandidatesRepo
     knowledge_build_runs: IKnowledgeBuildRunsRepo
+    problem_runs: IProblemRunsRepo
     vector_search: IVectorSearch | None
 
     @abstractmethod

app/core/use_cases/scenarios/__init__.py

@@ -0,0 +1 @@
+"""Scenario use cases for explicit problem-solving run windows."""

app/core/use_cases/scenarios/record/__init__.py

@@ -0,0 +1,15 @@
+"""Record one bounded problem-solving scenario."""
+
+from app.core.use_cases.scenarios.record.execute import execute_record_scenario
+from app.core.use_cases.scenarios.record.request import (
+    ScenarioRecordBody,
+    ScenarioRecordRequest,
+)
+from app.core.use_cases.scenarios.record.result import ScenarioRecordResult
+
+__all__ = [
+    "ScenarioRecordBody",
+    "ScenarioRecordRequest",
+    "ScenarioRecordResult",
+    "execute_record_scenario",
+]