shellbrain 0.1.56__tar.gz → 0.1.58__tar.gz

{shellbrain-0.1.56 → shellbrain-0.1.58}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: shellbrain
-Version: 0.1.56
+Version: 0.1.58
 Summary: Repo-scoped Shellbrain CLI with explicit evidence-backed writes.
 Requires-Python: >=3.11
 Description-Content-Type: text/markdown
@@ -20,7 +20,7 @@ Requires-Dist: sentence-transformers<4.0,>=3.0
 
 <p align="center">Long-term Memory for AI Agents.</p>
 
-ShellBrain gives AI agents memory, so they can store and reuse what they learn over time.
+ShellBrain carries useful lessons from one agent task to the next. It preserves decision reasons, failed approaches, product direction, and preferences that the resulting code does not explain.
 
 ## Install
 
@@ -53,13 +53,13 @@ You can also run `curl -L shellbrain.ai/upgrade | bash`. Manual alternative: `pi
 
 ## Architecture
 
-ShellBrain builds memory in three grounded layers:
+ShellBrain stores evidence and two forms of reusable knowledge:
 
 - **Episodic knowledge records evidence.** It stores prompts, agent steps, tool calls, and outputs from each session.
 - **Empirical knowledge extracts concrete memories.** It organizes problems, solutions, failed tactics, facts, preferences, and changes in a semantic graph for **case-based reasoning**.
 - **Conceptual knowledge abstracts reusable ideas.** Its concept graph connects claims, relations, and implementations to empirical knowledge.
 
-Each higher layer links to evidence in the layer below it. Agents receive a compact orientation first, then request more detail when needed.
+Memories and concept claims link to supporting evidence. A concept can express a product principle without a duplicate memory. Current code remains the source of truth for implementation details.
 
 ---
 
@@ -98,7 +98,7 @@ shellbrain recall "What is ShellBrain, and how does it help a working coding age
 }
 ```
 
-The brief lets the working agent focus on the current task.
+Recall selects an evidence pack in code, then asks an inner agent to summarize it. Source attribution comes from the selected records. Fast mode and provider failures return a brief directly from that same pack.
 
 ### Teach
 

{shellbrain-0.1.56 → shellbrain-0.1.58}/README.md

@@ -6,7 +6,7 @@
 
 <p align="center">Long-term Memory for AI Agents.</p>
 
-ShellBrain gives AI agents memory, so they can store and reuse what they learn over time.
+ShellBrain carries useful lessons from one agent task to the next. It preserves decision reasons, failed approaches, product direction, and preferences that the resulting code does not explain.
 
 ## Install
 
@@ -39,13 +39,13 @@ You can also run `curl -L shellbrain.ai/upgrade | bash`. Manual alternative: `pi
 
 ## Architecture
 
-ShellBrain builds memory in three grounded layers:
+ShellBrain stores evidence and two forms of reusable knowledge:
 
 - **Episodic knowledge records evidence.** It stores prompts, agent steps, tool calls, and outputs from each session.
 - **Empirical knowledge extracts concrete memories.** It organizes problems, solutions, failed tactics, facts, preferences, and changes in a semantic graph for **case-based reasoning**.
 - **Conceptual knowledge abstracts reusable ideas.** Its concept graph connects claims, relations, and implementations to empirical knowledge.
 
-Each higher layer links to evidence in the layer below it. Agents receive a compact orientation first, then request more detail when needed.
+Memories and concept claims link to supporting evidence. A concept can express a product principle without a duplicate memory. Current code remains the source of truth for implementation details.
 
 ---
 
@@ -84,7 +84,7 @@ shellbrain recall "What is ShellBrain, and how does it help a working coding age
 }
 ```
 
-The brief lets the working agent focus on the current task.
+Recall selects an evidence pack in code, then asks an inner agent to summarize it. Source attribution comes from the selected records. Fast mode and provider failures return a brief directly from that same pack.
 
 ### Teach
 

{shellbrain-0.1.56 → shellbrain-0.1.58}/app/core/entities/backups.py

@@ -31,15 +31,5 @@ class BackupManifest:
     compression: str
 
 
-@dataclass(frozen=True)
-class BackupVerificationResult:
-    """Stable result for a verified backup artifact."""
-
-    backup_id: BackupId
-    artifact_sha256: str
-    artifact_size_bytes: int
-    verified: bool
-
-
 class BackupPolicyError(RuntimeError):
     """Raised when a backup or restore request violates core safety policy."""

{shellbrain-0.1.56 → shellbrain-0.1.58}/app/core/entities/concepts.py

@@ -159,14 +159,6 @@ class ConceptCreatedBy(str, Enum):
     IMPORT = "import"
 
 
-class GraphPatchStatus(str, Enum):
-    """Allowed graph patch lifecycle states."""
-
-    PENDING = "pending"
-    APPLIED = "applied"
-    REJECTED = "rejected"
-
-
 @dataclass(frozen=True, kw_only=True)
 class Concept:
     """One durable concept container."""
@@ -311,18 +303,3 @@ class ConceptEvidence:
     transcript_ref: str | None = None
     note: str | None = None
     created_at: datetime | None = None
-
-
-@dataclass(frozen=True, kw_only=True)
-class GraphPatch:
-    """Minimal reserved future graph-patch proposal record."""
-
-    id: str
-    repo_id: str
-    schema_version: str
-    status: GraphPatchStatus
-    proposed_by: ConceptCreatedBy
-    operations_json: list[dict[str, Any]]
-    evidence_summary: str | None = None
-    created_at: datetime | None = None
-    applied_at: datetime | None = None

{shellbrain-0.1.56 → shellbrain-0.1.58}/app/core/entities/episodes.py

@@ -1,4 +1,4 @@
-"""This module defines episodic session entities and transfer provenance entities."""
+"""This module defines episodic session entities."""
 
 from dataclasses import dataclass
 from datetime import datetime
@@ -30,8 +30,6 @@ class Episode:
     repo_id: str
     host_app: str
     thread_id: str | None = None
-    title: str | None = None
-    objective: str | None = None
     status: EpisodeStatus = EpisodeStatus.ACTIVE
     started_at: datetime | None = None
     ended_at: datetime | None = None
@@ -77,18 +75,3 @@ class EpisodeEvent:
     source: EpisodeEventSource
     content: str
     created_at: datetime | None = None
-
-
-@dataclass(kw_only=True)
-class SessionTransfer:
-    """This dataclass models immutable cross-session transfer provenance."""
-
-    id: str
-    repo_id: str
-    from_episode_id: str
-    to_episode_id: str
-    event_id: str
-    transfer_kind: str
-    rationale: str | None = None
-    transferred_by: str | None = None
-    created_at: datetime | None = None

{shellbrain-0.1.56 → shellbrain-0.1.58}/app/core/entities/guidance.py

@@ -26,7 +26,6 @@ class GuidanceDecision:
     problem_id: str | None = None
     memory_ids: list[str] = field(default_factory=list)
     vote_scale_hint: dict[str, float] | None = None
-    setup_hint: str | None = None
 
     def to_payload(self) -> dict[str, Any]:
         """Serialize one guidance decision into the public response shape."""
@@ -42,6 +41,4 @@ class GuidanceDecision:
             payload["memory_ids"] = list(self.memory_ids)
         if self.vote_scale_hint is not None:
             payload["vote_scale_hint"] = dict(self.vote_scale_hint)
-        if self.setup_hint is not None:
-            payload["setup_hint"] = self.setup_hint
         return payload

{shellbrain-0.1.56 → shellbrain-0.1.58}/app/core/entities/identity.py

@@ -17,17 +17,6 @@ class IdentityTrustLevel(str, Enum):
 SUPPORTED_HOST_APPS = frozenset({"codex", "claude_code", "cursor"})
 
 
-def build_canonical_caller_id(
-    *, host_app: str, host_session_key: str, agent_key: str | None = None
-) -> str:
-    """Build the canonical caller identifier from one host session and optional agent key."""
-
-    canonical = f"{host_app}:{host_session_key}"
-    if agent_key:
-        canonical = f"{canonical}:agent:{agent_key}"
-    return canonical
-
-
 @dataclass(frozen=True, kw_only=True)
 class CallerIdentity:
     """Canonical caller identity used to scope episodes, session state, and guidance."""
@@ -57,11 +46,9 @@ class CallerIdentity:
             object.__setattr__(
                 self, "trust_level", IdentityTrustLevel(str(self.trust_level))
             )
-        canonical_id = build_canonical_caller_id(
-            host_app=host_app,
-            host_session_key=host_session_key,
-            agent_key=self.agent_key,
-        )
+        canonical_id = f"{host_app}:{host_session_key}"
+        if self.agent_key:
+            canonical_id = f"{canonical_id}:agent:{self.agent_key}"
         if self.canonical_id is not None and self.canonical_id != canonical_id:
             raise ValueError(
                 "canonical_id must match host_app, host_session_key, and agent_key"

{shellbrain-0.1.56 → shellbrain-0.1.58}/app/core/entities/ids.py

@@ -10,9 +10,7 @@ RepoId = NewType("RepoId", str)
 EpisodeId = NewType("EpisodeId", str)
 EvidenceRefText = NewType("EvidenceRefText", str)
 EvidenceId = NewType("EvidenceId", str)
-InvocationId = NewType("InvocationId", str)
 AssociationEdgeId = NewType("AssociationEdgeId", str)
 
 Confidence = NewType("Confidence", float)
 Salience = NewType("Salience", float)
-UtilityVote = NewType("UtilityVote", float)

{shellbrain-0.1.56 → shellbrain-0.1.58}/app/core/entities/inner_agents.py

@@ -15,7 +15,7 @@ InnerAgentName = Literal["build_context", "build_knowledge", "teach"]
 InnerAgentProviderName = str
 InnerAgentReasoningLevel = Literal["none", "minimal", "low", "medium", "high", "xhigh"]
 BuildContextStrategy = Literal[
-    "deterministic_synthesis", "deterministic_only", "autonomous"
+    "deterministic_synthesis", "deterministic_only"
 ]
 TokenCaptureQuality = Literal["exact", "estimated"]
 InnerAgentRunStatus = Literal[
@@ -36,7 +36,6 @@ class BuildContextSettings(_StrictModel):
     model: str = Field(min_length=1)
     reasoning: InnerAgentReasoningLevel
     timeout_seconds: int = Field(ge=1, le=600)
-    max_private_reads: int = Field(default=0, ge=0, le=10)
     max_brief_tokens: int | None = Field(default=None, ge=1, le=100_000)
 
 

{shellbrain-0.1.56 → shellbrain-0.1.58}/app/core/entities/memories.py

@@ -34,17 +34,11 @@ class MemoryKind(str, Enum):
 
         return self in {MemoryKind.SOLUTION, MemoryKind.FAILED_TACTIC}
 
-MATURE_MEMORY_KINDS: Final[tuple[MemoryKind, ...]] = (
-    MemoryKind.PROBLEM,
-    MemoryKind.SOLUTION,
-    MemoryKind.FAILED_TACTIC,
-    MemoryKind.FACT,
-    MemoryKind.PREFERENCE,
-    MemoryKind.CHANGE,
-)
 MATURE_MEMORY_KIND_VALUES: Final[tuple[str, ...]] = tuple(
-    kind.value for kind in MATURE_MEMORY_KINDS
+    kind.value for kind in MemoryKind
 )
+
+
 class MemoryScope(str, Enum):
     """This enum defines shellbrain visibility scope."""
 

{shellbrain-0.1.56 → shellbrain-0.1.58}/app/core/entities/settings.py

@@ -89,28 +89,8 @@ class ReadPolicySettings:
         }
 
 
-@dataclass(frozen=True)
-class CreatePolicySettings:
-    """Create-policy validation and hydration settings."""
-
-    gates: tuple[str, ...]
-    defaults: Mapping[str, Any]
-
-    def hydration_defaults(self) -> dict[str, Any]:
-        return dict(self.defaults)
-
-    def to_dict(self) -> dict[str, Any]:
-        return {"gates": list(self.gates), "defaults": dict(self.defaults)}
-
 
-@dataclass(frozen=True)
-class UpdatePolicySettings:
-    """Update-policy validation settings."""
 
-    gates: tuple[str, ...]
-
-    def to_dict(self) -> dict[str, Any]:
-        return {"gates": list(self.gates)}
 
 
 @dataclass(frozen=True)

{shellbrain-0.1.56 → shellbrain-0.1.58}/app/core/entities/snapshots.py

@@ -32,13 +32,6 @@ class ShadowGitPathChangeStatus(str, Enum):
     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."""
 
@@ -211,13 +204,10 @@ class AvailableCodeDeltaContext:
     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",
@@ -248,7 +238,7 @@ class AvailableCodeDeltaContext:
         """Return the stable JSON payload for bounded events."""
 
         return {
-            "status": self.status.value,
+            "status": "available",
             "base_snapshot_id": self.base_snapshot_id,
             "final_snapshot_id": self.final_snapshot_id,
             "base_shadow_commit_sha": self.base_shadow_commit_sha,
@@ -266,22 +256,17 @@ 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}
+        return {"status": "unavailable", "reason": self.reason.value}
 
 
 CodeDeltaContext = AvailableCodeDeltaContext | UnavailableCodeDeltaContext

{shellbrain-0.1.56 → shellbrain-0.1.58}/app/core/errors.py

@@ -16,12 +16,9 @@ class ErrorCode(str, Enum):
     NOT_FOUND = "not_found"
     CONFLICT = "conflict"
     INTERNAL_ERROR = "internal_error"
-    HOST_IDENTITY_UNAVAILABLE = "host_identity_unavailable"
     HOST_IDENTITY_UNSUPPORTED = "host_identity_unsupported"
     HOST_IDENTITY_DRIFTED = "host_identity_drifted"
     HOST_HOOK_MISSING = "host_hook_missing"
-    TRANSCRIPT_SOURCE_NOT_FOUND = "transcript_source_not_found"
-    INNER_AGENT_ERROR = "inner_agent_error"
 
 
 class ErrorDetail(BaseModel):

{shellbrain-0.1.56 → shellbrain-0.1.58}/app/core/policies/retrieval/bm25.py

@@ -36,9 +36,6 @@ class BM25ScoredDocument:
 def score_documents(
     query_terms: Sequence[str],
     documents: Sequence[BM25Document],
-    *,
-    k1: float = _K1,
-    b: float = _B,
 ) -> list[BM25ScoredDocument]:
     """Return BM25 scores and weighted query coverage for partially matching documents."""
 
@@ -81,12 +78,12 @@ def score_documents(
         score = 0.0
         matched_query_weight = 0.0
         document_length = len(document.terms)
-        normalization = k1 * (1 - b + b * document_length / average_length)
+        normalization = _K1 * (1 - _B + _B * document_length / average_length)
         for term in matched_terms:
             inverse_document_frequency = inverse_document_frequencies[term]
             term_frequency = frequencies[term]
             score += inverse_document_frequency * (
-                (term_frequency * (k1 + 1)) / (term_frequency + normalization)
+                (term_frequency * (_K1 + 1)) / (term_frequency + normalization)
             )
             matched_query_weight += inverse_document_frequency
 

{shellbrain-0.1.56 → shellbrain-0.1.58}/app/core/policies/retrieval/lexical_query.py

@@ -43,8 +43,6 @@ _STOPWORDS = frozenset(
 class LexicalQuery:
     """Normalized lexical query terms used by the keyword retrieval lane."""
 
-    raw_terms: tuple[str, ...]
-    informative_terms: tuple[str, ...]
     terms: tuple[str, ...]
     uses_stopword_fallback: bool
 
@@ -68,14 +66,11 @@ def build_lexical_query(query_text: str) -> LexicalQuery:
     """Build a normalized lexical query with strict informative-term semantics."""
 
     normalized = normalize_lexical_text(query_text)
-    raw_terms = _unique_terms(normalized.raw_terms)
-    informative_terms = _unique_terms(normalized.informative_terms)
+    raw_terms = tuple(dict.fromkeys(normalized.raw_terms))
+    informative_terms = tuple(dict.fromkeys(normalized.informative_terms))
     uses_stopword_fallback = not informative_terms and bool(raw_terms)
-    terms = raw_terms if uses_stopword_fallback else informative_terms
     return LexicalQuery(
-        raw_terms=raw_terms,
-        informative_terms=informative_terms,
-        terms=terms,
+        terms=raw_terms if uses_stopword_fallback else informative_terms,
         uses_stopword_fallback=uses_stopword_fallback,
     )
 
@@ -88,16 +83,3 @@ def normalize_lexical_text(text: str) -> NormalizedLexicalText:
     return NormalizedLexicalText(
         raw_terms=raw_terms, informative_terms=informative_terms
     )
-
-
-def _unique_terms(terms: tuple[str, ...]) -> tuple[str, ...]:
-    """Deduplicate terms while preserving original order."""
-
-    seen: set[str] = set()
-    ordered: list[str] = []
-    for term in terms:
-        if term in seen:
-            continue
-        seen.add(term)
-        ordered.append(term)
-    return tuple(ordered)

{shellbrain-0.1.56 → shellbrain-0.1.58}/app/core/policies/retrieval/ontology_semantics.py

@@ -5,34 +5,23 @@ from __future__ import annotations
 from collections import Counter
 from typing import Any, Iterable, Mapping
 
+from app.core.entities.memories import (
+    DEFAULT_RETRIEVABLE_MEMORY_STATUS_VALUES,
+    MemoryLifecycleStatus,
+)
 
-ACTIVE_STATUS = "active"
-MAYBE_STALE_STATUS = "maybe_stale"
-STALE_STATUS = "stale"
-SUPERSEDED_STATUS = "superseded"
-WRONG_STATUS = "wrong"
-ARCHIVED_STATUS = "archived"
 
-POSITIVE_LIFECYCLE_STATUSES = frozenset(
-    {ACTIVE_STATUS, MAYBE_STALE_STATUS, STALE_STATUS}
-)
+ACTIVE_STATUS = MemoryLifecycleStatus.ACTIVE.value
+MAYBE_STALE_STATUS = MemoryLifecycleStatus.MAYBE_STALE.value
+STALE_STATUS = MemoryLifecycleStatus.STALE.value
+SUPERSEDED_STATUS = MemoryLifecycleStatus.SUPERSEDED.value
+WRONG_STATUS = MemoryLifecycleStatus.WRONG.value
+ARCHIVED_STATUS = MemoryLifecycleStatus.ARCHIVED.value
 
-LIFECYCLE_RETRIEVAL_MULTIPLIERS: Mapping[str, float] = {
-    ACTIVE_STATUS: 1.0,
-    MAYBE_STALE_STATUS: 0.65,
-    STALE_STATUS: 0.25,
-    SUPERSEDED_STATUS: 0.0,
-    WRONG_STATUS: 0.0,
-    ARCHIVED_STATUS: 0.0,
-}
+POSITIVE_LIFECYCLE_STATUSES = frozenset(DEFAULT_RETRIEVABLE_MEMORY_STATUS_VALUES)
 
-BUNDLE_FRESHNESS_MULTIPLIERS: Mapping[str, float] = {
-    ACTIVE_STATUS: 1.0,
-    MAYBE_STALE_STATUS: 0.75,
-    STALE_STATUS: 0.45,
-    SUPERSEDED_STATUS: 0.0,
-    WRONG_STATUS: 0.0,
-    ARCHIVED_STATUS: 0.0,
+LIFECYCLE_RETRIEVAL_MULTIPLIERS: Mapping[str, float] = {
+    status.value: status.retrieval_multiplier for status in MemoryLifecycleStatus
 }
 
 CONCEPT_MEMORY_HIGH_SIGNAL_ROLES = frozenset(
@@ -54,13 +43,6 @@ STRUCTURAL_FACT_UPDATE_RELATION_PREDICATES = (
 
 REVERSIBLE_ASSOCIATION_RELATION_TYPES = frozenset({"associated_with"})
 
-_STATUS_PRECEDENCE = (
-    WRONG_STATUS,
-    ARCHIVED_STATUS,
-    SUPERSEDED_STATUS,
-    STALE_STATUS,
-    MAYBE_STALE_STATUS,
-)
 _STRUCTURAL_EXPANSION_BY_PREDICATE = {
     "solved_by": "problem_attempt",
     "failed_with": "problem_attempt",
@@ -87,6 +69,8 @@ def lifecycle_retrieval_multiplier(status: Any) -> float:
     """Return the default positive retrieval multiplier for one lifecycle status."""
 
     return LIFECYCLE_RETRIEVAL_MULTIPLIERS[normalize_lifecycle_status(status)]
+
+
 def is_active_lifecycle(status: Any) -> bool:
     """Return whether a lifecycle status is active."""
 
@@ -111,37 +95,14 @@ def lifecycle_status_counts(statuses: Iterable[Any]) -> dict[str, int]:
     }
 
 
-def dominant_lifecycle_status(statuses: Iterable[Any]) -> str:
-    """Return the status that should dominate currentness interpretation."""
-
-    normalized = tuple(normalize_lifecycle_status(status) for status in statuses)
-    for status in _STATUS_PRECEDENCE:
-        if status in normalized:
-            return status
-    return ACTIVE_STATUS
-
-
-def concept_bundle_retrieval_multiplier(statuses: Iterable[Any]) -> float:
-    """Return the freshness multiplier for an aggregate concept bundle."""
+def bundle_lifecycle_statuses(bundle: Mapping[str, Any]) -> tuple[str, ...]:
+    """Return lifecycle status values across every truth-bearing concept facet."""
 
-    return BUNDLE_FRESHNESS_MULTIPLIERS[dominant_lifecycle_status(statuses)]
-
-
-def aggregate_currentness_payload(
-    statuses: Iterable[Any], *, record_label: str
-) -> dict[str, str]:
-    """Return currentness text for a group of truth-bearing records."""
-
-    status = dominant_lifecycle_status(statuses)
-    if status == ACTIVE_STATUS:
-        return {
-            "currentness": "current",
-            "temporal_reason": f"all included {record_label} are active",
-        }
-    return {
-        "currentness": status,
-        "temporal_reason": f"one or more {record_label} are marked {status}",
-    }
+    return tuple(
+        record.lifecycle.status.value
+        for key in ("claims", "relations", "groundings", "memory_links")
+        for record in bundle[key]
+    )
 
 
 def lifecycle_currentness_payload(
@@ -203,7 +164,9 @@ def structural_relation_expansion_type(predicate: Any) -> str:
     try:
         return _STRUCTURAL_EXPANSION_BY_PREDICATE[value]
     except KeyError as exc:
-        raise ValueError(f"unsupported structural memory relation predicate: {value}") from exc
+        raise ValueError(
+            f"unsupported structural memory relation predicate: {value}"
+        ) from exc
 
 
 def why_included_for_expansion(expansion_type: str) -> str:

{shellbrain-0.1.56 → shellbrain-0.1.58}/app/core/ports/db/concept_repositories.py

@@ -12,7 +12,6 @@ from app.core.entities.concepts import (
     ConceptLifecycleTargetType,
     ConceptMemoryLink,
     ConceptRelation,
-    GraphPatch,
 )
 
 
@@ -84,10 +83,6 @@ class IConceptsRepo(ABC):
     ) -> ConceptLifecycleEvent:
         """This method appends one auditable concept lifecycle transition."""
 
-    @abstractmethod
-    def create_graph_patch(self, patch: GraphPatch) -> GraphPatch:
-        """This method stores one future graph-patch proposal record."""
-
     @abstractmethod
     def get_concept_bundle(
         self,

{shellbrain-0.1.56 → shellbrain-0.1.58}/app/core/ports/db/episode_repositories.py

@@ -1,15 +1,9 @@
 """Repository ports for episode persistence."""
 
 from abc import ABC, abstractmethod
-from datetime import datetime
 from typing import Sequence
 
-from app.core.entities.episodes import (
-    Episode,
-    EpisodeBuildSnapshot,
-    EpisodeEvent,
-    SessionTransfer,
-)
+from app.core.entities.episodes import Episode, EpisodeBuildSnapshot, EpisodeEvent
 
 
 class IEpisodesRepo(ABC):
@@ -55,10 +49,6 @@ class IEpisodesRepo(ABC):
     ) -> 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."""
-
     @abstractmethod
     def next_event_seq(self, *, episode_id: str) -> int:
         """This method returns the next append sequence number for one episode."""
@@ -71,14 +61,6 @@ class IEpisodesRepo(ABC):
     def append_event_if_new(self, event: EpisodeEvent) -> bool:
         """This method appends an event only when its host_event_key is not already present."""
 
-    @abstractmethod
-    def close_episode(self, *, episode_id: str, ended_at: datetime) -> None:
-        """This method marks an active episode closed."""
-
-    @abstractmethod
-    def append_transfer(self, transfer: SessionTransfer) -> None:
-        """This method appends a cross-session transfer row."""
-
     @abstractmethod
     def list_existing_event_ids(self, *, event_ids: Sequence[str]) -> Sequence[str]:
         """This method returns episode-event ids that exist anywhere in storage."""

{shellbrain-0.1.56 → shellbrain-0.1.58}/app/core/ports/host_apps/inner_agents.py

@@ -31,12 +31,10 @@ class InnerAgentRunRequest(_StrictModel):
     model: str = Field(min_length=1)
     reasoning: InnerAgentReasoningLevel
     timeout_seconds: int = Field(ge=1, le=600)
-    max_private_reads: int = Field(default=0, ge=0, le=10)
     max_brief_tokens: int | None = Field(default=None, ge=1, le=100_000)
     query: str = Field(min_length=1)
     repo_root: str | None = None
-    synthesis_only: bool = False
-    deterministic_pack: dict[str, Any] | None = None
+    deterministic_pack: dict[str, Any]
 
 
 class InnerAgentRunResult(_StrictModel):
@@ -61,7 +59,6 @@ class InnerAgentRunResult(_StrictModel):
     concept_expansion_count: int = Field(default=0, ge=0)
     error_code: str | None = None
     error_message: str | None = None
-    read_trace: dict[str, Any] = Field(default_factory=dict)
 
 
 class BuildKnowledgeAgentRequest(_StrictModel):

{shellbrain-0.1.56 → shellbrain-0.1.58}/app/core/use_cases/admin/backfill_model_usage/__init__.py

@@ -5,13 +5,11 @@ from app.core.use_cases.admin.backfill_model_usage.backfill_model_usage import (
     linked_session_from_mapping,
 )
 from app.core.use_cases.admin.backfill_model_usage.request import (
-    BackfillModelUsageRequest,
     LinkedModelUsageSession,
 )
 from app.core.use_cases.admin.backfill_model_usage.result import BackfillSummary
 
 __all__ = [
-    "BackfillModelUsageRequest",
     "BackfillSummary",
     "LinkedModelUsageSession",
     "backfill_model_usage",