shellbrain 0.1.0__py3-none-any.whl

app/periphery/cli/presenter_json.py

@@ -0,0 +1,10 @@
+"""This module defines deterministic JSON presentation helpers for CLI responses."""
+
+import json
+from typing import Any
+
+
+def render(payload: dict[str, Any]) -> str:
+    """This function renders payloads as deterministic compact JSON output."""
+
+    return json.dumps(payload, separators=(",", ":"))

app/periphery/cli/schema_validation.py

@@ -0,0 +1,201 @@
+"""CLI schema-validation helpers for strict request contracts."""
+
+from typing import Any, Literal
+
+from pydantic import Field, ValidationError, field_validator
+
+from app.core.contracts.errors import ErrorCode, ErrorDetail
+from app.core.contracts.requests import (
+    BatchUtilityVoteItem,
+    EpisodeEventsRequest,
+    MemoryBatchUpdateRequest,
+    MemoryCreateLinks,
+    MemoryCreateRequest,
+    MemoryReadRequest,
+    MemoryUpdateRequest,
+    StrictBaseModel,
+    UpdatePayload,
+    UtilityVoteUpdate,
+)
+
+
+class AgentReadRequest(StrictBaseModel):
+    """Agent-facing read payload with config-only retrieval knobs removed."""
+
+    op: Literal["read"] = "read"
+    repo_id: str | None = None
+    mode: Literal["ambient", "targeted"] | None = None
+    query: str = Field(min_length=1)
+    include_global: bool | None = None
+    kinds: (
+        list[Literal["problem", "solution", "failed_tactic", "fact", "preference", "change"]] | None
+    ) = None
+    limit: int | None = Field(default=None, ge=1, le=100)
+
+    @field_validator("kinds")
+    @classmethod
+    def _validate_kinds_unique(
+        cls,
+        value: list[Literal["problem", "solution", "failed_tactic", "fact", "preference", "change"]] | None,
+    ) -> list[Literal["problem", "solution", "failed_tactic", "fact", "preference", "change"]] | None:
+        """This validator enforces unique kinds filters for agent read requests."""
+
+        if value is None:
+            return value
+        if len(value) != len(set(value)):
+            raise ValueError("kinds must be unique")
+        return value
+
+
+class AgentCreateBody(StrictBaseModel):
+    """Agent-facing create payload with transport fields removed."""
+
+    text: str
+    scope: Literal["repo", "global"] | None = None
+    kind: Literal["problem", "solution", "failed_tactic", "fact", "preference", "change"]
+    rationale: str | None = None
+    links: MemoryCreateLinks = Field(default_factory=MemoryCreateLinks)
+    evidence_refs: list[str] = Field(min_length=1)
+
+    @field_validator("evidence_refs")
+    @classmethod
+    def _validate_evidence_unique(cls, value: list[str]) -> list[str]:
+        """This validator enforces unique evidence references for agent create requests."""
+
+        if len(value) != len(set(value)):
+            raise ValueError("evidence_refs must be unique")
+        return value
+
+
+class AgentCreateRequest(StrictBaseModel):
+    """Agent-facing create payload with repo/op transport details removed."""
+
+    memory: AgentCreateBody
+
+
+class AgentEventsRequest(StrictBaseModel):
+    """Agent-facing events payload with transport fields removed."""
+
+    limit: int | None = Field(default=None, ge=1, le=100)
+
+
+class AgentUpdateRequest(StrictBaseModel):
+    """Agent-facing update payload with repo/op transport details removed."""
+
+    memory_id: str
+    update: UpdatePayload
+
+
+class AgentBatchUpdateItem(StrictBaseModel):
+    """Agent-facing batch utility item with transport fields removed."""
+
+    memory_id: str
+    update: UtilityVoteUpdate
+
+
+class AgentBatchUpdateRequest(StrictBaseModel):
+    """Agent-facing batch utility update payload."""
+
+    updates: list[AgentBatchUpdateItem] = Field(min_length=1)
+
+
+def _format_validation_errors(exc: ValidationError) -> list[ErrorDetail]:
+    """Convert Pydantic validation errors into contract error details."""
+
+    details: list[ErrorDetail] = []
+    for item in exc.errors():
+        path = ".".join(str(segment) for segment in item.get("loc", ()))
+        message = item.get("msg", "Schema validation failed")
+        if path in {"memory.evidence_refs", "update.evidence_refs"} and item.get("type") in {
+            "too_short",
+            "missing",
+        }:
+            message = "evidence_refs must include at least one stored episode event id; query events first"
+        details.append(
+            ErrorDetail(
+                code=ErrorCode.SCHEMA_ERROR,
+                message=message,
+                field=path or None,
+            )
+        )
+    return details
+
+
+def validate_create_schema(payload: dict[str, Any]) -> tuple[AgentCreateRequest | None, list[ErrorDetail]]:
+    """Validate and parse agent create payloads into the simplified create contract."""
+
+    try:
+        return AgentCreateRequest.model_validate(payload), []
+    except ValidationError as exc:
+        return None, _format_validation_errors(exc)
+
+
+def validate_read_schema(payload: dict[str, Any]) -> tuple[AgentReadRequest | None, list[ErrorDetail]]:
+    """Validate and parse agent read payloads into the simplified read contract."""
+
+    try:
+        return AgentReadRequest.model_validate(payload), []
+    except ValidationError as exc:
+        return None, _format_validation_errors(exc)
+
+
+def validate_events_schema(payload: dict[str, Any]) -> tuple[AgentEventsRequest | None, list[ErrorDetail]]:
+    """Validate and parse agent events payloads into the simplified events contract."""
+
+    try:
+        return AgentEventsRequest.model_validate(payload), []
+    except ValidationError as exc:
+        return None, _format_validation_errors(exc)
+
+
+def validate_internal_read_contract(payload: dict[str, Any]) -> tuple[MemoryReadRequest | None, list[ErrorDetail]]:
+    """Validate one hydrated read payload against the full internal read contract."""
+
+    try:
+        return MemoryReadRequest.model_validate(payload), []
+    except ValidationError as exc:
+        return None, _format_validation_errors(exc)
+
+
+def validate_internal_events_contract(
+    payload: dict[str, Any],
+) -> tuple[EpisodeEventsRequest | None, list[ErrorDetail]]:
+    """Validate one hydrated events payload against the full internal events contract."""
+
+    try:
+        return EpisodeEventsRequest.model_validate(payload), []
+    except ValidationError as exc:
+        return None, _format_validation_errors(exc)
+
+
+def validate_internal_create_contract(payload: dict[str, Any]) -> tuple[MemoryCreateRequest | None, list[ErrorDetail]]:
+    """Validate one hydrated create payload against the full internal create contract."""
+
+    try:
+        return MemoryCreateRequest.model_validate(payload), []
+    except ValidationError as exc:
+        return None, _format_validation_errors(exc)
+
+
+def validate_update_schema(payload: dict[str, Any]) -> tuple[AgentUpdateRequest | None, list[ErrorDetail]]:
+    """Validate and parse agent update payloads into the simplified update contract."""
+
+    try:
+        if "updates" in payload:
+            return AgentBatchUpdateRequest.model_validate(payload), []
+        return AgentUpdateRequest.model_validate(payload), []
+    except ValidationError as exc:
+        return None, _format_validation_errors(exc)
+
+
+def validate_internal_update_contract(
+    payload: dict[str, Any],
+) -> tuple[MemoryUpdateRequest | MemoryBatchUpdateRequest | None, list[ErrorDetail]]:
+    """Validate one hydrated update payload against the full internal update contract."""
+
+    try:
+        if "updates" in payload:
+            return MemoryBatchUpdateRequest.model_validate(payload), []
+        return MemoryUpdateRequest.model_validate(payload), []
+    except ValidationError as exc:
+        return None, _format_validation_errors(exc)

app/periphery/db/__init__.py

@@ -0,0 +1 @@
+"""This package contains database models, repositories, and transaction wiring."""

app/periphery/db/engine.py

@@ -0,0 +1,10 @@
+"""This module defines PostgreSQL engine construction helpers for application boot wiring."""
+
+from sqlalchemy import create_engine
+from sqlalchemy.engine import Engine
+
+
+def get_engine(dsn: str) -> Engine:
+    """This function creates a SQLAlchemy engine for the provided PostgreSQL DSN."""
+
+    return create_engine(dsn, future=True)

app/periphery/db/models/__init__.py

@@ -0,0 +1 @@
+"""This package defines SQLAlchemy Core table and view metadata."""

app/periphery/db/models/associations.py

@@ -0,0 +1,55 @@
+"""This module defines SQLAlchemy Core tables for association edges and observations."""
+
+from sqlalchemy import CheckConstraint, Column, Float, ForeignKey, Integer, String, Table, UniqueConstraint
+from sqlalchemy.dialects.postgresql import TIMESTAMP
+
+from app.periphery.db.models.metadata import metadata
+
+
+association_edges = Table(
+    "association_edges",
+    metadata,
+    Column("id", String, primary_key=True),
+    Column("repo_id", String, nullable=False),
+    Column("from_memory_id", String, ForeignKey("memories.id", ondelete="CASCADE"), nullable=False),
+    Column("to_memory_id", String, ForeignKey("memories.id", ondelete="CASCADE"), nullable=False),
+    Column("relation_type", String, nullable=False),
+    Column("source_mode", String, nullable=False),
+    Column("state", String, nullable=False),
+    Column("strength", Float, nullable=False, default=0.0),
+    Column("obs_count", Integer, nullable=False, default=0),
+    Column("positive_obs", Integer, nullable=False, default=0),
+    Column("negative_obs", Integer, nullable=False, default=0),
+    Column("salience_sum", Float, nullable=False, default=0.0),
+    Column("last_reinforced_at", TIMESTAMP(timezone=True)),
+    Column("last_used_at", TIMESTAMP(timezone=True)),
+    Column("created_at", TIMESTAMP(timezone=True), nullable=False),
+    Column("updated_at", TIMESTAMP(timezone=True), nullable=False),
+    CheckConstraint("from_memory_id <> to_memory_id", name="ck_association_edges_no_self_loop"),
+    UniqueConstraint("repo_id", "from_memory_id", "to_memory_id", "relation_type", name="uq_association_edges_pair"),
+)
+
+association_observations = Table(
+    "association_observations",
+    metadata,
+    Column("id", String, primary_key=True),
+    Column("repo_id", String, nullable=False),
+    Column("edge_id", String, ForeignKey("association_edges.id", ondelete="CASCADE")),
+    Column("from_memory_id", String, ForeignKey("memories.id", ondelete="CASCADE"), nullable=False),
+    Column("to_memory_id", String, ForeignKey("memories.id", ondelete="CASCADE"), nullable=False),
+    Column("relation_type", String, nullable=False),
+    Column("source", String, nullable=False),
+    Column("problem_id", String, ForeignKey("memories.id", ondelete="SET NULL")),
+    Column("episode_id", String, ForeignKey("episodes.id", ondelete="SET NULL")),
+    Column("valence", Float, nullable=False),
+    Column("salience", Float, nullable=False, default=0.5),
+    Column("created_at", TIMESTAMP(timezone=True), nullable=False),
+    CheckConstraint("from_memory_id <> to_memory_id", name="ck_association_observations_no_self_loop"),
+)
+
+association_edge_evidence = Table(
+    "association_edge_evidence",
+    metadata,
+    Column("edge_id", String, ForeignKey("association_edges.id", ondelete="CASCADE"), primary_key=True),
+    Column("evidence_id", String, ForeignKey("evidence_refs.id", ondelete="CASCADE"), primary_key=True),
+)

app/periphery/db/models/episodes.py

@@ -0,0 +1,55 @@
+"""This module defines SQLAlchemy Core tables for episodes, events, and session transfers."""
+
+from sqlalchemy import CheckConstraint, Column, ForeignKey, Integer, String, Table, Text, UniqueConstraint
+from sqlalchemy.dialects.postgresql import TIMESTAMP
+
+from app.periphery.db.models.metadata import metadata
+
+
+episodes = Table(
+    "episodes",
+    metadata,
+    Column("id", String, primary_key=True),
+    Column("repo_id", String, nullable=False),
+    Column("host_app", String, nullable=False),
+    Column("thread_id", String),
+    Column("title", String),
+    Column("objective", String),
+    Column("status", String, nullable=False),
+    Column("started_at", TIMESTAMP(timezone=True), nullable=False),
+    Column("ended_at", TIMESTAMP(timezone=True)),
+    Column("created_at", TIMESTAMP(timezone=True), nullable=False),
+    UniqueConstraint("repo_id", "thread_id", name="uq_episodes_repo_thread"),
+    CheckConstraint("ended_at IS NULL OR ended_at >= started_at", name="ck_episodes_ended_after_started"),
+)
+
+episode_events = Table(
+    "episode_events",
+    metadata,
+    Column("id", String, primary_key=True),
+    Column("episode_id", String, ForeignKey("episodes.id", ondelete="CASCADE"), nullable=False),
+    Column("seq", Integer, nullable=False),
+    Column("host_event_key", String, nullable=False),
+    Column("source", String, nullable=False),
+    Column("content", Text, nullable=False),
+    Column("created_at", TIMESTAMP(timezone=True), nullable=False),
+    CheckConstraint("seq > 0", name="ck_episode_events_seq_positive"),
+    UniqueConstraint("episode_id", "seq", name="uq_episode_events_seq"),
+    UniqueConstraint("episode_id", "host_event_key", name="uq_episode_events_host_event_key"),
+)
+
+session_transfers = Table(
+    "session_transfers",
+    metadata,
+    Column("id", String, primary_key=True),
+    Column("repo_id", String, nullable=False),
+    Column("from_episode_id", String, ForeignKey("episodes.id", ondelete="CASCADE"), nullable=False),
+    Column("to_episode_id", String, ForeignKey("episodes.id", ondelete="CASCADE"), nullable=False),
+    Column("event_id", String, ForeignKey("episode_events.id", ondelete="CASCADE"), nullable=False),
+    Column("transfer_kind", String, nullable=False),
+    Column("rationale", Text),
+    Column("transferred_by", String),
+    Column("created_at", TIMESTAMP(timezone=True), nullable=False),
+    CheckConstraint("from_episode_id <> to_episode_id", name="ck_session_transfers_distinct_episodes"),
+    UniqueConstraint("from_episode_id", "to_episode_id", "event_id", "transfer_kind", name="uq_session_transfers_transfer"),
+)

app/periphery/db/models/evidence.py

@@ -0,0 +1,19 @@
+"""This module defines SQLAlchemy Core tables for evidence reference records."""
+
+from sqlalchemy import Column, ForeignKey, String, Table, UniqueConstraint
+from sqlalchemy.dialects.postgresql import TIMESTAMP
+
+from app.periphery.db.models.metadata import metadata
+
+
+evidence_refs = Table(
+    "evidence_refs",
+    metadata,
+    Column("id", String, primary_key=True),
+    Column("repo_id", String, nullable=False),
+    Column("ref", String, nullable=False),
+    Column("episode_event_id", String, ForeignKey("episode_events.id"), nullable=True),
+    Column("created_at", TIMESTAMP(timezone=True), nullable=False),
+    UniqueConstraint("repo_id", "ref", name="uq_evidence_repo_ref"),
+    UniqueConstraint("repo_id", "episode_event_id", name="uq_evidence_repo_episode_event"),
+)

app/periphery/db/models/experiences.py

@@ -0,0 +1,33 @@
+"""This module defines SQLAlchemy Core tables for problem attempts and fact updates."""
+
+from sqlalchemy import CheckConstraint, Column, ForeignKey, String, Table, UniqueConstraint
+from sqlalchemy.dialects.postgresql import TIMESTAMP
+
+from app.periphery.db.models.metadata import metadata
+
+
+problem_attempts = Table(
+    "problem_attempts",
+    metadata,
+    Column("problem_id", String, ForeignKey("memories.id", ondelete="CASCADE"), primary_key=True),
+    Column("attempt_id", String, ForeignKey("memories.id", ondelete="CASCADE"), primary_key=True),
+    Column("role", String, nullable=False),
+    Column("created_at", TIMESTAMP(timezone=True), nullable=False),
+    CheckConstraint("problem_id <> attempt_id", name="ck_problem_attempts_distinct_memories"),
+)
+
+fact_updates = Table(
+    "fact_updates",
+    metadata,
+    Column("id", String, primary_key=True),
+    Column("old_fact_id", String, ForeignKey("memories.id", ondelete="CASCADE"), nullable=False),
+    Column("change_id", String, ForeignKey("memories.id", ondelete="CASCADE"), nullable=False),
+    Column("new_fact_id", String, ForeignKey("memories.id", ondelete="CASCADE"), nullable=False),
+    Column("created_at", TIMESTAMP(timezone=True), nullable=False),
+    CheckConstraint("old_fact_id <> new_fact_id", name="ck_fact_updates_distinct_fact_endpoints"),
+    CheckConstraint(
+        "change_id <> old_fact_id AND change_id <> new_fact_id",
+        name="ck_fact_updates_change_id_distinct",
+    ),
+    UniqueConstraint("old_fact_id", "change_id", "new_fact_id", name="uq_fact_updates_chain"),
+)

app/periphery/db/models/instance_metadata.py

@@ -0,0 +1,17 @@
+"""SQLAlchemy Core table for instance classification and safety metadata."""
+
+from sqlalchemy import Column, String, Table, Text
+from sqlalchemy.dialects.postgresql import TIMESTAMP
+
+from app.periphery.db.models.metadata import metadata
+
+
+instance_metadata = Table(
+    "instance_metadata",
+    metadata,
+    Column("instance_id", String, primary_key=True),
+    Column("instance_mode", String, nullable=False),
+    Column("created_at", TIMESTAMP(timezone=True), nullable=False),
+    Column("created_by", String, nullable=False),
+    Column("notes", Text, nullable=True),
+)

app/periphery/db/models/memories.py

@@ -0,0 +1,39 @@
+"""This module defines SQLAlchemy Core tables for memories and shellbrain embeddings."""
+
+from pgvector.sqlalchemy import Vector
+from sqlalchemy import Boolean, CheckConstraint, Column, ForeignKey, Integer, String, Table, Text, UniqueConstraint
+from sqlalchemy.dialects.postgresql import TIMESTAMP
+
+from app.periphery.db.models.metadata import metadata
+
+
+memories = Table(
+    "memories",
+    metadata,
+    Column("id", String, primary_key=True),
+    Column("repo_id", String, nullable=False),
+    Column("scope", String, nullable=False),
+    Column("kind", String, nullable=False),
+    Column("text", Text, nullable=False),
+    Column("created_at", TIMESTAMP(timezone=True), nullable=False),
+    Column("archived", Boolean, nullable=False, default=False),
+)
+
+memory_embeddings = Table(
+    "memory_embeddings",
+    metadata,
+    Column("memory_id", String, ForeignKey("memories.id", ondelete="CASCADE"), primary_key=True),
+    Column("model", String, nullable=False),
+    Column("dim", Integer, nullable=False),
+    Column("vector", Vector(), nullable=False),
+    Column("created_at", TIMESTAMP(timezone=True), nullable=False),
+    CheckConstraint("dim > 0", name="ck_memory_embeddings_dim_positive"),
+)
+
+memory_evidence = Table(
+    "memory_evidence",
+    metadata,
+    Column("memory_id", String, ForeignKey("memories.id", ondelete="CASCADE"), primary_key=True),
+    Column("evidence_id", String, ForeignKey("evidence_refs.id", ondelete="CASCADE"), primary_key=True),
+    UniqueConstraint("memory_id", "evidence_id", name="uq_memory_evidence_pair"),
+)

app/periphery/db/models/metadata.py

@@ -0,0 +1,6 @@
+"""This module defines shared SQLAlchemy metadata and naming conventions for DB models."""
+
+from sqlalchemy import MetaData
+
+
+metadata = MetaData()

app/periphery/db/models/registry.py

@@ -0,0 +1,18 @@
+"""This module imports all SQLAlchemy table modules so metadata is fully registered."""
+
+from app.periphery.db.models import (
+    associations,
+    episodes,
+    evidence,
+    experiences,
+    instance_metadata,
+    memories,
+    telemetry,
+    utility,
+)
+from app.periphery.db.models.metadata import metadata
+
+
+_ = (associations, episodes, evidence, experiences, instance_metadata, memories, telemetry, utility)
+
+target_metadata = metadata

app/periphery/db/models/telemetry.py

@@ -0,0 +1,174 @@
+"""SQLAlchemy Core tables for low-overhead usage telemetry storage."""
+
+from sqlalchemy import Boolean, Column, ForeignKey, Index, Integer, String, Table, Text, text
+from sqlalchemy.dialects.postgresql import JSONB, TIMESTAMP
+
+from app.periphery.db.models.metadata import metadata
+
+
+operation_invocations = Table(
+    "operation_invocations",
+    metadata,
+    Column("id", String, primary_key=True),
+    Column("command", String, nullable=False),
+    Column("repo_id", String, nullable=False),
+    Column("repo_root", Text, nullable=False),
+    Column("no_sync", Boolean, nullable=False, server_default=text("FALSE")),
+    Column("caller_id", String),
+    Column("caller_trust_level", String),
+    Column("identity_failure_code", String),
+    Column("selected_host_app", String),
+    Column("selected_host_session_key", String),
+    Column("selected_thread_id", String),
+    Column("selected_episode_id", String),
+    Column("matching_candidate_count", Integer, nullable=False, server_default=text("0")),
+    Column("selection_ambiguous", Boolean, nullable=False, server_default=text("FALSE")),
+    Column("outcome", String, nullable=False),
+    Column("error_stage", String),
+    Column("error_code", String),
+    Column("error_message", Text),
+    Column("total_latency_ms", Integer, nullable=False),
+    Column("poller_start_attempted", Boolean, nullable=False, server_default=text("FALSE")),
+    Column("poller_started", Boolean, nullable=False, server_default=text("FALSE")),
+    Column("guidance_codes", JSONB, nullable=False, server_default=text("'[]'::jsonb")),
+    Column("created_at", TIMESTAMP(timezone=True), nullable=False, server_default=text("NOW()")),
+)
+
+read_invocation_summaries = Table(
+    "read_invocation_summaries",
+    metadata,
+    Column(
+        "invocation_id",
+        String,
+        ForeignKey("operation_invocations.id", ondelete="CASCADE"),
+        primary_key=True,
+    ),
+    Column("query_text", Text, nullable=False),
+    Column("mode", String, nullable=False),
+    Column("requested_limit", Integer),
+    Column("effective_limit", Integer, nullable=False),
+    Column("include_global", Boolean),
+    Column("kinds_filter", JSONB),
+    Column("direct_count", Integer, nullable=False),
+    Column("explicit_related_count", Integer, nullable=False),
+    Column("implicit_related_count", Integer, nullable=False),
+    Column("total_returned", Integer, nullable=False),
+    Column("zero_results", Boolean, nullable=False),
+    Column("created_at", TIMESTAMP(timezone=True), nullable=False, server_default=text("NOW()")),
+)
+
+read_result_items = Table(
+    "read_result_items",
+    metadata,
+    Column(
+        "invocation_id",
+        String,
+        ForeignKey("operation_invocations.id", ondelete="CASCADE"),
+        primary_key=True,
+    ),
+    Column("ordinal", Integer, primary_key=True),
+    Column("memory_id", String, nullable=False),
+    Column("kind", String, nullable=False),
+    Column("section", String, nullable=False),
+    Column("priority", Integer, nullable=False),
+    Column("why_included", String, nullable=False),
+    Column("anchor_memory_id", String),
+    Column("relation_type", String),
+)
+
+write_invocation_summaries = Table(
+    "write_invocation_summaries",
+    metadata,
+    Column(
+        "invocation_id",
+        String,
+        ForeignKey("operation_invocations.id", ondelete="CASCADE"),
+        primary_key=True,
+    ),
+    Column("operation_command", String, nullable=False),
+    Column("target_memory_id", String, nullable=False),
+    Column("target_kind", String),
+    Column("update_type", String),
+    Column("scope", String),
+    Column("evidence_ref_count", Integer, nullable=False, server_default=text("0")),
+    Column("planned_effect_count", Integer, nullable=False),
+    Column("created_memory_count", Integer, nullable=False, server_default=text("0")),
+    Column("archived_memory_count", Integer, nullable=False, server_default=text("0")),
+    Column("utility_observation_count", Integer, nullable=False, server_default=text("0")),
+    Column("association_effect_count", Integer, nullable=False, server_default=text("0")),
+    Column("fact_update_count", Integer, nullable=False, server_default=text("0")),
+    Column("created_at", TIMESTAMP(timezone=True), nullable=False, server_default=text("NOW()")),
+)
+
+write_effect_items = Table(
+    "write_effect_items",
+    metadata,
+    Column(
+        "invocation_id",
+        String,
+        ForeignKey("operation_invocations.id", ondelete="CASCADE"),
+        primary_key=True,
+    ),
+    Column("ordinal", Integer, primary_key=True),
+    Column("effect_type", String, nullable=False),
+    Column("repo_id", String, nullable=False),
+    Column("primary_memory_id", String),
+    Column("secondary_memory_id", String),
+    Column("params_json", JSONB, nullable=False, server_default=text("'{}'::jsonb")),
+)
+
+episode_sync_runs = Table(
+    "episode_sync_runs",
+    metadata,
+    Column("id", String, primary_key=True),
+    Column("source", String, nullable=False),
+    Column("invocation_id", String, ForeignKey("operation_invocations.id", ondelete="SET NULL")),
+    Column("repo_id", String, nullable=False),
+    Column("host_app", String, nullable=False),
+    Column("host_session_key", String, nullable=False),
+    Column("thread_id", String, nullable=False),
+    Column("episode_id", String),
+    Column("transcript_path", Text),
+    Column("outcome", String, nullable=False),
+    Column("error_stage", String),
+    Column("error_message", Text),
+    Column("duration_ms", Integer, nullable=False),
+    Column("imported_event_count", Integer, nullable=False, server_default=text("0")),
+    Column("total_event_count", Integer, nullable=False, server_default=text("0")),
+    Column("user_event_count", Integer, nullable=False, server_default=text("0")),
+    Column("assistant_event_count", Integer, nullable=False, server_default=text("0")),
+    Column("tool_event_count", Integer, nullable=False, server_default=text("0")),
+    Column("system_event_count", Integer, nullable=False, server_default=text("0")),
+    Column("created_at", TIMESTAMP(timezone=True), nullable=False, server_default=text("NOW()")),
+)
+
+episode_sync_tool_types = Table(
+    "episode_sync_tool_types",
+    metadata,
+    Column(
+        "sync_run_id",
+        String,
+        ForeignKey("episode_sync_runs.id", ondelete="CASCADE"),
+        primary_key=True,
+    ),
+    Column("tool_type", String, primary_key=True),
+    Column("event_count", Integer, nullable=False),
+)
+
+Index("idx_operation_invocations_repo_created_at", operation_invocations.c.repo_id, operation_invocations.c.created_at)
+Index("idx_operation_invocations_command_created_at", operation_invocations.c.command, operation_invocations.c.created_at)
+Index(
+    "idx_operation_invocations_thread_created_at",
+    operation_invocations.c.selected_thread_id,
+    operation_invocations.c.created_at,
+    postgresql_where=operation_invocations.c.selected_thread_id.is_not(None),
+)
+Index("idx_read_result_items_memory_invocation", read_result_items.c.memory_id, read_result_items.c.invocation_id)
+Index(
+    "idx_write_effect_items_repo_effect_invocation",
+    write_effect_items.c.repo_id,
+    write_effect_items.c.effect_type,
+    write_effect_items.c.invocation_id,
+)
+Index("idx_episode_sync_runs_repo_host_created_at", episode_sync_runs.c.repo_id, episode_sync_runs.c.host_app, episode_sync_runs.c.created_at)
+Index("idx_episode_sync_runs_thread_created_at", episode_sync_runs.c.thread_id, episode_sync_runs.c.created_at)