shellbrain 0.1.36__tar.gz → 0.1.37__tar.gz

{shellbrain-0.1.36 → shellbrain-0.1.37}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: shellbrain
-Version: 0.1.36
+Version: 0.1.37
 Summary: Repo-scoped Shellbrain CLI with explicit evidence-backed writes.
 Requires-Python: >=3.11
 Description-Content-Type: text/markdown
@@ -57,7 +57,7 @@ Episodic, empirical, conceptual. Three categories, one retrieval surface.
 - An ontology of problems, solutions, failed tactics, facts, preferences, changes.
 - This is **case-based reasoning** in a semantic graph.
 
-**Conceptual konwledge** is the _abstractive_ layer.
+**Conceptual knowledge** is the _abstractive_ layer.
 - A **higher-level concept graph** with claims, relations, and implementations that link back to the concrete layer.
 - **Progressive disclosure.** agents get oriented first, then ask for depth only where tasks require it.
 
@@ -72,7 +72,37 @@ The episodic layer is truth. Empirical memory extracts. Concept memory abstracts
 **Working agents call `shellbrain recall`.** That is the normal interface they have to think about. One command, **one _carefully curated_ compact brief**, with sources cited.
 
 ```bash
-shellbrain recall --json '{"query":"what context matters for this migration lock timeout?","current_problem":{"goal":"fix the migration hang","surface":"db admin","obstacle":"lock timeout","hypothesis":"none yet"}}'
+shellbrain recall --json '{"query":"What is ShellBrain and how does it help a working coding agent?","current_problem":{"goal":"understand ShellBrain","surface":"README","obstacle":"new readers do not know the product yet","hypothesis":"a real recall brief should show what agents get back"}}'
+```
+
+Response shape:
+
+```json
+{
+  "status": "ok",
+  "data": {
+    "brief": {
+      "summary": "...",
+      "constraints": ["..."],
+      "known_traps": ["..."],
+      "prior_cases": ["..."],
+      "concept_orientation": ["..."],
+      "anchors": ["`README.md`"],
+      "conflicts": ["..."],
+      "gaps": ["..."],
+      "next_checks": ["..."],
+      "sources": [
+        {
+          "kind": "memory",
+          "id": "...",
+          "section": "direct"
+        }
+      ]
+    },
+    "fallback_reason": null
+  },
+  "errors": []
+}
 ```
 
 **Working agents focus on only their work.**
@@ -113,8 +143,4 @@ Use Shellbrain in your agent of choice. Then, just work normally.
 
 - [shellbrain.ai/humans](https://shellbrain.ai/humans/) — install, upgrade, getting started
 - [shellbrain.ai/agents](https://shellbrain.ai/agents/) — agent workflow and write discipline
-- [shellbrain.ai/recall](https://shellbrain.ai/recall/) — retrieval pipeline
-- [shellbrain.ai/memory/episodic](https://shellbrain.ai/memory/episodic/) — transcript evidence
-- [shellbrain.ai/memory/semantic](https://shellbrain.ai/memory/semantic/) — facts, preferences, changes
-- [shellbrain.ai/memory/procedural](https://shellbrain.ai/memory/procedural/) — problems, solutions, failed tactics
-- [shellbrain.ai/memory/associative](https://shellbrain.ai/memory/associative/) — explicit links and semantic neighbors
+- [shellbrain.ai/architecture](https://shellbrain.ai/architecture/) — memory model, storage, and boundaries

{shellbrain-0.1.36 → shellbrain-0.1.37}/README.md

@@ -43,7 +43,7 @@ Episodic, empirical, conceptual. Three categories, one retrieval surface.
 - An ontology of problems, solutions, failed tactics, facts, preferences, changes.
 - This is **case-based reasoning** in a semantic graph.
 
-**Conceptual konwledge** is the _abstractive_ layer.
+**Conceptual knowledge** is the _abstractive_ layer.
 - A **higher-level concept graph** with claims, relations, and implementations that link back to the concrete layer.
 - **Progressive disclosure.** agents get oriented first, then ask for depth only where tasks require it.
 
@@ -58,7 +58,37 @@ The episodic layer is truth. Empirical memory extracts. Concept memory abstracts
 **Working agents call `shellbrain recall`.** That is the normal interface they have to think about. One command, **one _carefully curated_ compact brief**, with sources cited.
 
 ```bash
-shellbrain recall --json '{"query":"what context matters for this migration lock timeout?","current_problem":{"goal":"fix the migration hang","surface":"db admin","obstacle":"lock timeout","hypothesis":"none yet"}}'
+shellbrain recall --json '{"query":"What is ShellBrain and how does it help a working coding agent?","current_problem":{"goal":"understand ShellBrain","surface":"README","obstacle":"new readers do not know the product yet","hypothesis":"a real recall brief should show what agents get back"}}'
+```
+
+Response shape:
+
+```json
+{
+  "status": "ok",
+  "data": {
+    "brief": {
+      "summary": "...",
+      "constraints": ["..."],
+      "known_traps": ["..."],
+      "prior_cases": ["..."],
+      "concept_orientation": ["..."],
+      "anchors": ["`README.md`"],
+      "conflicts": ["..."],
+      "gaps": ["..."],
+      "next_checks": ["..."],
+      "sources": [
+        {
+          "kind": "memory",
+          "id": "...",
+          "section": "direct"
+        }
+      ]
+    },
+    "fallback_reason": null
+  },
+  "errors": []
+}
 ```
 
 **Working agents focus on only their work.**
@@ -99,8 +129,4 @@ Use Shellbrain in your agent of choice. Then, just work normally.
 
 - [shellbrain.ai/humans](https://shellbrain.ai/humans/) — install, upgrade, getting started
 - [shellbrain.ai/agents](https://shellbrain.ai/agents/) — agent workflow and write discipline
-- [shellbrain.ai/recall](https://shellbrain.ai/recall/) — retrieval pipeline
-- [shellbrain.ai/memory/episodic](https://shellbrain.ai/memory/episodic/) — transcript evidence
-- [shellbrain.ai/memory/semantic](https://shellbrain.ai/memory/semantic/) — facts, preferences, changes
-- [shellbrain.ai/memory/procedural](https://shellbrain.ai/memory/procedural/) — problems, solutions, failed tactics
-- [shellbrain.ai/memory/associative](https://shellbrain.ai/memory/associative/) — explicit links and semantic neighbors
+- [shellbrain.ai/architecture](https://shellbrain.ai/architecture/) — memory model, storage, and boundaries

shellbrain-0.1.37/app/core/entities/snapshots.py

@@ -0,0 +1,288 @@
+"""Entities for repo-local shadow snapshots and solution deltas."""
+
+from __future__ import annotations
+
+from dataclasses import dataclass
+from datetime import datetime
+from enum import Enum
+
+
+class SnapshotCaptureStatus(str, Enum):
+    """Public result states for `shellbrain snapshot`."""
+
+    CREATED = "created"
+    NOOP = "noop"
+    BASELINE_ONLY = "baseline_only"
+
+
+class ShadowSnapshotReason(str, Enum):
+    """Why one shadow snapshot row exists."""
+
+    BASELINE = "baseline"
+    CLOSEOUT = "closeout"
+    BASELINE_ONLY = "baseline_only"
+
+
+class ShadowGitPathChangeStatus(str, Enum):
+    """Path-level change statuses reported by shadow Git diffs."""
+
+    ADDED = "added"
+    MODIFIED = "modified"
+    DELETED = "deleted"
+    RENAMED = "renamed"
+
+
+class CodeDeltaContextStatus(str, Enum):
+    """Public availability states for code-delta context."""
+
+    AVAILABLE = "available"
+    UNAVAILABLE = "unavailable"
+
+
+class CodeDeltaUnavailableReason(str, Enum):
+    """Expected reasons an event window cannot expose code-delta context."""
+
+    MISSING_BASE_SNAPSHOT = "missing_base_snapshot"
+    MISSING_FINAL_SNAPSHOT = "missing_final_snapshot"
+    BASE_AND_FINAL_SNAPSHOT_MATCH = "base_and_final_snapshot_match"
+    BASELINE_ONLY_BASE_SNAPSHOT = "baseline_only_base_snapshot"
+    BASELINE_ONLY_FINAL_SNAPSHOT = "baseline_only_final_snapshot"
+    EMPTY_DELTA = "empty_delta"
+
+
+@dataclass(frozen=True, kw_only=True)
+class ShadowGitPathChange:
+    """One path-level change between two shadow Git commits."""
+
+    status: ShadowGitPathChangeStatus
+    path: str
+    old_path: str | None = None
+
+    def __post_init__(self) -> None:
+        """Keep path-change status and rename metadata honest."""
+
+        if not isinstance(self.status, ShadowGitPathChangeStatus):
+            raise ValueError("status must be a ShadowGitPathChangeStatus")
+        if not isinstance(self.path, str) or not self.path.strip():
+            raise ValueError("path must be a non-empty string")
+        if self.status is ShadowGitPathChangeStatus.RENAMED:
+            if not isinstance(self.old_path, str) or not self.old_path.strip():
+                raise ValueError("old_path is required for renamed paths")
+        elif self.old_path is not None:
+            raise ValueError("old_path is valid only for renamed paths")
+
+    def to_response_data(self) -> dict[str, str]:
+        """Return the stable JSON payload for one path change."""
+
+        data = {"status": self.status.value, "path": self.path}
+        if self.old_path is not None:
+            data["old_path"] = self.old_path
+        return data
+
+
+@dataclass(frozen=True, kw_only=True)
+class ShadowSnapshot:
+    """One captured repo state stored in repo-local shadow Git."""
+
+    id: str
+    repo_id: str
+    repo_root: str
+    shadow_commit_sha: str
+    changed_paths: tuple[str, ...]
+    reason: ShadowSnapshotReason
+    parent_shadow_commit_sha: str | None = None
+    episode_id: str | None = None
+    captured_after_event_seq: int | None = None
+    operation_invocation_id: str | None = None
+    created_at: datetime | None = None
+
+    def __post_init__(self) -> None:
+        """Reject malformed snapshot identity before persistence."""
+
+        for field_name in ("id", "repo_id", "repo_root", "shadow_commit_sha"):
+            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 not isinstance(self.reason, ShadowSnapshotReason):
+            raise ValueError("reason must be a ShadowSnapshotReason")
+        if (
+            self.captured_after_event_seq is not None
+            and self.captured_after_event_seq < 0
+        ):
+            raise ValueError("captured_after_event_seq must be non-negative")
+
+
+@dataclass(frozen=True, kw_only=True)
+class SolutionDelta:
+    """Patch identity linking one solved problem run to concrete code evidence."""
+
+    id: str
+    problem_run_id: str
+    repo_id: str
+    repo_root: str
+    base_snapshot_id: str
+    final_snapshot_id: str
+    patch_sha: str
+    changed_paths: tuple[str, ...]
+    episode_id: str | None = None
+    created_at: datetime | None = None
+
+    def __post_init__(self) -> None:
+        """Reject invalid delta identity before persistence."""
+
+        for field_name in (
+            "id",
+            "problem_run_id",
+            "repo_id",
+            "repo_root",
+            "base_snapshot_id",
+            "final_snapshot_id",
+            "patch_sha",
+        ):
+            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.base_snapshot_id == self.final_snapshot_id:
+            raise ValueError("solution delta requires distinct snapshots")
+
+
+@dataclass(frozen=True, kw_only=True)
+class ShadowGitCaptureRequest:
+    """Core request passed to the shadow Git storage port."""
+
+    snapshot_id: str
+    repo_id: str
+    repo_root: str
+    reason: ShadowSnapshotReason
+    episode_id: str | None = None
+    captured_after_event_seq: int | None = None
+    operation_invocation_id: str | None = None
+
+
+class ShadowGitCaptureState(str, Enum):
+    """Storage-level capture result states."""
+
+    CREATED = "created"
+    NOOP = "noop"
+
+
+@dataclass(frozen=True, kw_only=True)
+class ShadowGitCaptureResult:
+    """Result returned by the shadow Git storage port."""
+
+    state: ShadowGitCaptureState
+    shadow_commit_sha: str | None
+    parent_shadow_commit_sha: str | None
+    changed_paths: tuple[str, ...]
+    tree_sha: str | None = None
+
+
+@dataclass(frozen=True, kw_only=True)
+class ShadowGitDiffResult:
+    """Patch identity returned by the shadow Git storage port."""
+
+    patch_sha: str
+    path_changes: tuple[ShadowGitPathChange, ...]
+
+    def __post_init__(self) -> None:
+        """Reject malformed patch identity before core code trusts it."""
+
+        if not isinstance(self.patch_sha, str) or not self.patch_sha.strip():
+            raise ValueError("patch_sha must be a non-empty string")
+        for change in self.path_changes:
+            if not isinstance(change, ShadowGitPathChange):
+                raise ValueError(
+                    "path_changes must contain ShadowGitPathChange values"
+                )
+
+    @property
+    def changed_paths(self) -> tuple[str, ...]:
+        """Return changed final paths for existing callers and public payloads."""
+
+        return tuple(change.path for change in self.path_changes)
+
+
+@dataclass(frozen=True, kw_only=True)
+class AvailableCodeDeltaContext:
+    """Compact code-delta evidence for one bounded event window."""
+
+    base_snapshot_id: str
+    final_snapshot_id: str
+    base_shadow_commit_sha: str
+    final_shadow_commit_sha: str
+    patch_sha: str
+    path_changes: tuple[ShadowGitPathChange, ...]
+    status: CodeDeltaContextStatus = CodeDeltaContextStatus.AVAILABLE
+
+    def __post_init__(self) -> None:
+        """Reject invalid available-context states."""
+
+        if self.status is not CodeDeltaContextStatus.AVAILABLE:
+            raise ValueError("available code delta context requires available status")
+        for field_name in (
+            "base_snapshot_id",
+            "final_snapshot_id",
+            "base_shadow_commit_sha",
+            "final_shadow_commit_sha",
+            "patch_sha",
+        ):
+            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.base_snapshot_id == self.final_snapshot_id:
+            raise ValueError("code delta context requires distinct snapshots")
+        if not self.path_changes:
+            raise ValueError("available code delta context requires path changes")
+        for change in self.path_changes:
+            if not isinstance(change, ShadowGitPathChange):
+                raise ValueError(
+                    "path_changes must contain ShadowGitPathChange values"
+                )
+
+    @property
+    def changed_paths(self) -> tuple[str, ...]:
+        """Return changed final paths for compact consumers."""
+
+        return tuple(change.path for change in self.path_changes)
+
+    def to_response_data(self) -> dict[str, object]:
+        """Return the stable JSON payload for bounded events."""
+
+        return {
+            "status": self.status.value,
+            "base_snapshot_id": self.base_snapshot_id,
+            "final_snapshot_id": self.final_snapshot_id,
+            "base_shadow_commit_sha": self.base_shadow_commit_sha,
+            "final_shadow_commit_sha": self.final_shadow_commit_sha,
+            "patch_sha": self.patch_sha,
+            "path_changes": [
+                change.to_response_data() for change in self.path_changes
+            ],
+            "changed_paths": list(self.changed_paths),
+        }
+
+
+@dataclass(frozen=True, kw_only=True)
+class UnavailableCodeDeltaContext:
+    """Expected absence of code-delta evidence for one event window."""
+
+    reason: CodeDeltaUnavailableReason
+    status: CodeDeltaContextStatus = CodeDeltaContextStatus.UNAVAILABLE
+
+    def __post_init__(self) -> None:
+        """Reject unavailable-context states without a typed reason."""
+
+        if self.status is not CodeDeltaContextStatus.UNAVAILABLE:
+            raise ValueError(
+                "unavailable code delta context requires unavailable status"
+            )
+        if not isinstance(self.reason, CodeDeltaUnavailableReason):
+            raise ValueError("reason must be a CodeDeltaUnavailableReason")
+
+    def to_response_data(self) -> dict[str, str]:
+        """Return the stable JSON payload for bounded events."""
+
+        return {"status": self.status.value, "reason": self.reason.value}
+
+
+CodeDeltaContext = AvailableCodeDeltaContext | UnavailableCodeDeltaContext

shellbrain-0.1.37/app/core/ports/db/snapshots.py

@@ -0,0 +1,52 @@
+"""Persistence ports for shadow snapshots and solution deltas."""
+
+from __future__ import annotations
+
+from abc import ABC, abstractmethod
+
+from app.core.entities.snapshots import ShadowSnapshot, SolutionDelta
+
+
+class ISnapshotsRepo(ABC):
+    """Persistence behavior for code-evidence snapshots."""
+
+    @abstractmethod
+    def latest_snapshot(self, *, repo_id: str, repo_root: str) -> ShadowSnapshot | None:
+        """Return the newest shadow snapshot for one repo root."""
+
+    @abstractmethod
+    def latest_snapshot_at_or_before_event(
+        self,
+        *,
+        repo_id: str,
+        repo_root: str,
+        episode_id: str,
+        event_seq: int,
+    ) -> ShadowSnapshot | None:
+        """Return the latest valid base snapshot for an episode event boundary."""
+
+    @abstractmethod
+    def latest_snapshot_in_event_window(
+        self,
+        *,
+        repo_id: str,
+        repo_root: str,
+        episode_id: str,
+        opened_event_seq: int,
+        closed_event_seq: int,
+    ) -> ShadowSnapshot | None:
+        """Return the latest valid final snapshot captured in a scenario window."""
+
+    @abstractmethod
+    def get_solution_delta_for_problem_run(
+        self, *, problem_run_id: str
+    ) -> SolutionDelta | None:
+        """Return an existing delta for one problem run."""
+
+    @abstractmethod
+    def add_snapshot(self, snapshot: ShadowSnapshot) -> None:
+        """Persist one shadow snapshot metadata row."""
+
+    @abstractmethod
+    def add_solution_delta(self, delta: SolutionDelta) -> None:
+        """Persist one solution delta metadata row."""

{shellbrain-0.1.36 → shellbrain-0.1.37}/app/core/ports/db/unit_of_work.py

@@ -15,6 +15,7 @@ from app.core.ports.db.memory_repositories import (
     IUtilityRepo,
 )
 from app.core.ports.db.problem_runs import IProblemRunsRepo
+from app.core.ports.db.snapshots import ISnapshotsRepo
 from app.core.ports.embeddings.retrieval import IVectorSearch
 from app.core.ports.db.retrieval_repositories import (
     IConceptKeywordRetrievalRepo,
@@ -43,6 +44,7 @@ class IUnitOfWork(ABC):
     guidance: IPendingUtilityCandidatesRepo
     knowledge_build_runs: IKnowledgeBuildRunsRepo
     problem_runs: IProblemRunsRepo
+    snapshots: ISnapshotsRepo
     vector_search: IVectorSearch | None
 
     @abstractmethod

shellbrain-0.1.37/app/core/ports/local_state/shadow_git.py

@@ -0,0 +1,27 @@
+"""Core-owned port for repo-local shadow Git storage."""
+
+from __future__ import annotations
+
+from abc import ABC, abstractmethod
+
+from app.core.entities.snapshots import (
+    ShadowGitCaptureRequest,
+    ShadowGitCaptureResult,
+    ShadowGitDiffResult,
+)
+
+
+class IShadowGitStore(ABC):
+    """Filesystem/Git behavior needed by snapshot use cases."""
+
+    @abstractmethod
+    def capture_snapshot(
+        self, request: ShadowGitCaptureRequest
+    ) -> ShadowGitCaptureResult:
+        """Capture the current repo tree into shadow Git."""
+
+    @abstractmethod
+    def diff_snapshot_pair(
+        self, *, repo_root: str, base_commit_sha: str, final_commit_sha: str
+    ) -> ShadowGitDiffResult:
+        """Return a stable patch hash and changed paths for two shadow commits."""

{shellbrain-0.1.36 → shellbrain-0.1.37}/app/core/use_cases/scenarios/record/execute.py

@@ -6,13 +6,26 @@ from app.core.entities.episodes import Episode, EpisodeEvent
 from app.core.entities.memories import Memory, MemoryKind
 from app.core.entities.scenarios import (
     ProblemRun,
+    ScenarioOutcome,
     outcome_to_problem_run_status,
 )
+from app.core.entities.snapshots import (
+    AvailableCodeDeltaContext,
+    SolutionDelta,
+    UnavailableCodeDeltaContext,
+)
 from app.core.errors import DomainValidationError, ErrorCode, ErrorDetail
 from app.core.ports.db.unit_of_work import IUnitOfWork
+from app.core.ports.local_state.shadow_git import IShadowGitStore
 from app.core.ports.system.idgen import IIdGenerator
 from app.core.use_cases.scenarios.record.request import ScenarioRecordRequest
-from app.core.use_cases.scenarios.record.result import ScenarioRecordResult
+from app.core.use_cases.scenarios.record.result import (
+    ScenarioRecordResult,
+    SolutionDeltaRecordResult,
+)
+from app.core.use_cases.snapshots.code_delta_context import (
+    build_code_delta_context_from_snapshots,
+)
 
 
 _BUILD_KNOWLEDGE_ACTOR = "build_knowledge"
@@ -22,7 +35,9 @@ def execute_record_scenario(
     request: ScenarioRecordRequest,
     uow: IUnitOfWork,
     *,
+    repo_root: str,
     id_generator: IIdGenerator,
+    shadow_git_store: IShadowGitStore,
 ) -> ScenarioRecordResult:
     """Validate references and persist one scenario run window."""
 
@@ -55,6 +70,7 @@ def execute_record_scenario(
                 scenario_id=existing.id,
                 outcome=scenario.outcome,
                 created=False,
+                solution_delta=_existing_solution_delta_result(existing.id, uow),
             )
         raise DomainValidationError(
             [
@@ -84,10 +100,112 @@ def execute_record_scenario(
         solution_memory_id=solution_memory.id if solution_memory else None,
     )
     uow.problem_runs.add(run)
+    solution_delta_result = _attach_solution_delta(
+        request=request,
+        run=run,
+        repo_root=repo_root,
+        opened_event=opened_event,
+        closed_event=closed_event,
+        uow=uow,
+        id_generator=id_generator,
+        shadow_git_store=shadow_git_store,
+    )
     return ScenarioRecordResult(
         scenario_id=run.id,
         outcome=scenario.outcome,
         created=True,
+        solution_delta=solution_delta_result,
+    )
+
+
+def _existing_solution_delta_result(
+    problem_run_id: str, uow: IUnitOfWork
+) -> SolutionDeltaRecordResult:
+    """Return replay metadata for a previously attached solution delta."""
+
+    existing_delta = uow.snapshots.get_solution_delta_for_problem_run(
+        problem_run_id=problem_run_id
+    )
+    if existing_delta is None:
+        return SolutionDeltaRecordResult(
+            status="skipped", reason="existing_problem_run_has_no_solution_delta"
+        )
+    return SolutionDeltaRecordResult(
+        status="exists",
+        solution_delta_id=existing_delta.id,
+        base_snapshot_id=existing_delta.base_snapshot_id,
+        final_snapshot_id=existing_delta.final_snapshot_id,
+        patch_sha=existing_delta.patch_sha,
+        changed_paths=existing_delta.changed_paths,
+    )
+
+
+def _attach_solution_delta(
+    *,
+    request: ScenarioRecordRequest,
+    run: ProblemRun,
+    repo_root: str,
+    opened_event: EpisodeEvent,
+    closed_event: EpisodeEvent,
+    uow: IUnitOfWork,
+    id_generator: IIdGenerator,
+    shadow_git_store: IShadowGitStore,
+) -> SolutionDeltaRecordResult:
+    """Attach a patch-backed delta when a solved run has valid snapshots."""
+
+    if request.scenario.outcome is not ScenarioOutcome.SOLVED:
+        return SolutionDeltaRecordResult(status="skipped", reason="outcome_not_solved")
+
+    base_snapshot = uow.snapshots.latest_snapshot_at_or_before_event(
+        repo_id=request.repo_id,
+        repo_root=repo_root,
+        episode_id=request.scenario.episode_id,
+        event_seq=opened_event.seq,
+    )
+    if base_snapshot is None:
+        return SolutionDeltaRecordResult(status="skipped", reason="missing_base_snapshot")
+    final_snapshot = uow.snapshots.latest_snapshot_in_event_window(
+        repo_id=request.repo_id,
+        repo_root=repo_root,
+        episode_id=request.scenario.episode_id,
+        opened_event_seq=opened_event.seq,
+        closed_event_seq=closed_event.seq,
+    )
+    if final_snapshot is None:
+        return SolutionDeltaRecordResult(
+            status="skipped", reason="missing_final_snapshot"
+        )
+    code_delta_context = build_code_delta_context_from_snapshots(
+        repo_root=repo_root,
+        base_snapshot=base_snapshot,
+        final_snapshot=final_snapshot,
+        baseline_only_base_event_seq=opened_event.seq - 1,
+        shadow_git_store=shadow_git_store,
+    )
+    if isinstance(code_delta_context, UnavailableCodeDeltaContext):
+        return SolutionDeltaRecordResult(
+            status="skipped", reason=code_delta_context.reason.value
+        )
+    assert isinstance(code_delta_context, AvailableCodeDeltaContext)
+    delta = SolutionDelta(
+        id=id_generator.new_id(),
+        problem_run_id=run.id,
+        repo_id=request.repo_id,
+        repo_root=repo_root,
+        episode_id=request.scenario.episode_id,
+        base_snapshot_id=code_delta_context.base_snapshot_id,
+        final_snapshot_id=code_delta_context.final_snapshot_id,
+        patch_sha=code_delta_context.patch_sha,
+        changed_paths=code_delta_context.changed_paths,
+    )
+    uow.snapshots.add_solution_delta(delta)
+    return SolutionDeltaRecordResult(
+        status="created",
+        solution_delta_id=delta.id,
+        base_snapshot_id=delta.base_snapshot_id,
+        final_snapshot_id=delta.final_snapshot_id,
+        patch_sha=delta.patch_sha,
+        changed_paths=delta.changed_paths,
     )