shellbrain 0.1.0__py3-none-any.whl

app/migrations/versions/20260226_0001_initial_schema.py

@@ -0,0 +1,232 @@
+"""This migration creates the initial PostgreSQL schema, indexes, and derived views."""
+
+from alembic import op
+
+
+revision = "20260226_0001"
+down_revision = None
+branch_labels = None
+depends_on = None
+
+
+def upgrade() -> None:
+    """This function applies the initial schema for shellbrain storage and retrieval."""
+
+    op.execute(
+        """
+        CREATE EXTENSION IF NOT EXISTS vector;
+
+        CREATE TABLE memories (
+          id TEXT PRIMARY KEY,
+          repo_id TEXT NOT NULL,
+          scope TEXT NOT NULL CHECK (scope IN ('repo', 'global')),
+          kind TEXT NOT NULL CHECK (kind IN ('problem', 'solution', 'failed_tactic', 'fact', 'preference', 'change')),
+          text TEXT NOT NULL,
+          create_confidence DOUBLE PRECISION CHECK (create_confidence >= 0 AND create_confidence <= 1),
+          created_at TIMESTAMPTZ NOT NULL DEFAULT NOW(),
+          archived BOOLEAN NOT NULL DEFAULT FALSE
+        );
+        CREATE INDEX idx_memories_repo_scope_kind ON memories(repo_id, scope, kind);
+        CREATE INDEX idx_memories_created_at ON memories(created_at);
+        CREATE INDEX idx_memories_text_fts ON memories USING GIN (to_tsvector('english', text));
+
+        CREATE TABLE episodes (
+          id TEXT PRIMARY KEY,
+          repo_id TEXT NOT NULL,
+          thread_id TEXT,
+          title TEXT,
+          objective TEXT,
+          status TEXT NOT NULL DEFAULT 'active' CHECK (status IN ('active', 'closed', 'archived')),
+          started_at TIMESTAMPTZ NOT NULL DEFAULT NOW(),
+          ended_at TIMESTAMPTZ,
+          created_at TIMESTAMPTZ NOT NULL DEFAULT NOW()
+        );
+        CREATE INDEX idx_episodes_repo_status_started ON episodes(repo_id, status, started_at);
+        CREATE INDEX idx_episodes_repo_thread ON episodes(repo_id, thread_id);
+
+        CREATE TABLE episode_events (
+          id TEXT PRIMARY KEY,
+          episode_id TEXT NOT NULL REFERENCES episodes(id) ON DELETE CASCADE,
+          seq INTEGER NOT NULL CHECK (seq > 0),
+          source TEXT NOT NULL CHECK (source IN ('user', 'assistant', 'tool', 'system')),
+          content TEXT NOT NULL,
+          created_at TIMESTAMPTZ NOT NULL DEFAULT NOW(),
+          UNIQUE (episode_id, seq)
+        );
+        CREATE INDEX idx_episode_events_episode_created ON episode_events(episode_id, created_at);
+
+        CREATE TABLE session_transfers (
+          id TEXT PRIMARY KEY,
+          repo_id TEXT NOT NULL,
+          from_episode_id TEXT NOT NULL REFERENCES episodes(id) ON DELETE CASCADE,
+          to_episode_id TEXT NOT NULL REFERENCES episodes(id) ON DELETE CASCADE,
+          event_id TEXT NOT NULL REFERENCES episode_events(id) ON DELETE CASCADE,
+          transfer_kind TEXT NOT NULL CHECK (transfer_kind IN ('message_handoff', 'context_summary', 'task_split', 'task_merge')),
+          rationale TEXT,
+          transferred_by TEXT,
+          created_at TIMESTAMPTZ NOT NULL DEFAULT NOW(),
+          UNIQUE (from_episode_id, to_episode_id, event_id, transfer_kind)
+        );
+        CREATE INDEX idx_session_transfers_from ON session_transfers(from_episode_id, created_at);
+        CREATE INDEX idx_session_transfers_to ON session_transfers(to_episode_id, created_at);
+        CREATE INDEX idx_session_transfers_event ON session_transfers(event_id);
+
+        CREATE TABLE memory_embeddings (
+          memory_id TEXT PRIMARY KEY REFERENCES memories(id) ON DELETE CASCADE,
+          model TEXT NOT NULL,
+          dim INTEGER NOT NULL CHECK (dim > 0),
+          vector VECTOR NOT NULL,
+          created_at TIMESTAMPTZ NOT NULL DEFAULT NOW()
+        );
+
+        CREATE TABLE problem_attempts (
+          problem_id TEXT NOT NULL REFERENCES memories(id) ON DELETE CASCADE,
+          attempt_id TEXT NOT NULL REFERENCES memories(id) ON DELETE CASCADE,
+          role TEXT NOT NULL CHECK (role IN ('solution', 'failed_tactic')),
+          created_at TIMESTAMPTZ NOT NULL DEFAULT NOW(),
+          PRIMARY KEY (problem_id, attempt_id)
+        );
+        CREATE INDEX idx_problem_attempts_problem ON problem_attempts(problem_id);
+        CREATE INDEX idx_problem_attempts_attempt ON problem_attempts(attempt_id);
+
+        CREATE TABLE fact_updates (
+          id TEXT PRIMARY KEY,
+          old_fact_id TEXT NOT NULL REFERENCES memories(id) ON DELETE CASCADE,
+          change_id TEXT NOT NULL REFERENCES memories(id) ON DELETE CASCADE,
+          new_fact_id TEXT NOT NULL REFERENCES memories(id) ON DELETE CASCADE,
+          created_at TIMESTAMPTZ NOT NULL DEFAULT NOW(),
+          UNIQUE (old_fact_id, change_id, new_fact_id)
+        );
+        CREATE INDEX idx_fact_updates_old_fact ON fact_updates(old_fact_id);
+        CREATE INDEX idx_fact_updates_new_fact ON fact_updates(new_fact_id);
+
+        CREATE TABLE association_edges (
+          id TEXT PRIMARY KEY,
+          repo_id TEXT NOT NULL,
+          from_memory_id TEXT NOT NULL REFERENCES memories(id) ON DELETE CASCADE,
+          to_memory_id TEXT NOT NULL REFERENCES memories(id) ON DELETE CASCADE,
+          relation_type TEXT NOT NULL CHECK (relation_type IN ('depends_on', 'associated_with')),
+          source_mode TEXT NOT NULL DEFAULT 'agent' CHECK (source_mode IN ('agent', 'implicit', 'mixed')),
+          state TEXT NOT NULL DEFAULT 'tentative' CHECK (state IN ('tentative', 'confirmed', 'deprecated')),
+          strength DOUBLE PRECISION NOT NULL DEFAULT 0 CHECK (strength >= 0 AND strength <= 1),
+          obs_count INTEGER NOT NULL DEFAULT 0 CHECK (obs_count >= 0),
+          positive_obs INTEGER NOT NULL DEFAULT 0 CHECK (positive_obs >= 0),
+          negative_obs INTEGER NOT NULL DEFAULT 0 CHECK (negative_obs >= 0),
+          salience_sum DOUBLE PRECISION NOT NULL DEFAULT 0 CHECK (salience_sum >= 0),
+          last_reinforced_at TIMESTAMPTZ,
+          last_used_at TIMESTAMPTZ,
+          created_at TIMESTAMPTZ NOT NULL DEFAULT NOW(),
+          updated_at TIMESTAMPTZ NOT NULL DEFAULT NOW(),
+          CHECK (from_memory_id <> to_memory_id),
+          UNIQUE (repo_id, from_memory_id, to_memory_id, relation_type)
+        );
+        CREATE INDEX idx_assoc_edges_from ON association_edges(repo_id, from_memory_id, relation_type, state, strength);
+        CREATE INDEX idx_assoc_edges_to ON association_edges(repo_id, to_memory_id, relation_type, state, strength);
+
+        CREATE TABLE association_observations (
+          id TEXT PRIMARY KEY,
+          repo_id TEXT NOT NULL,
+          edge_id TEXT REFERENCES association_edges(id) ON DELETE CASCADE,
+          from_memory_id TEXT NOT NULL REFERENCES memories(id) ON DELETE CASCADE,
+          to_memory_id TEXT NOT NULL REFERENCES memories(id) ON DELETE CASCADE,
+          relation_type TEXT NOT NULL CHECK (relation_type IN ('depends_on', 'associated_with')),
+          source TEXT NOT NULL CHECK (source IN ('agent_explicit', 'implicit_coactivation', 'agent_feedback')),
+          problem_id TEXT REFERENCES memories(id) ON DELETE SET NULL,
+          episode_id TEXT REFERENCES episodes(id) ON DELETE SET NULL,
+          valence DOUBLE PRECISION NOT NULL CHECK (valence >= -1 AND valence <= 1),
+          salience DOUBLE PRECISION NOT NULL DEFAULT 0.5 CHECK (salience >= 0 AND salience <= 1),
+          created_at TIMESTAMPTZ NOT NULL DEFAULT NOW(),
+          CHECK (from_memory_id <> to_memory_id)
+        );
+        CREATE INDEX idx_assoc_obs_pair_time ON association_observations(repo_id, from_memory_id, to_memory_id, created_at);
+        CREATE INDEX idx_assoc_obs_problem ON association_observations(repo_id, problem_id, created_at);
+        CREATE INDEX idx_assoc_obs_episode ON association_observations(repo_id, episode_id, created_at);
+
+        CREATE TABLE utility_observations (
+          id TEXT PRIMARY KEY,
+          memory_id TEXT NOT NULL REFERENCES memories(id) ON DELETE CASCADE,
+          problem_id TEXT NOT NULL REFERENCES memories(id) ON DELETE CASCADE,
+          vote DOUBLE PRECISION NOT NULL CHECK (vote >= -1 AND vote <= 1),
+          rationale TEXT,
+          created_at TIMESTAMPTZ NOT NULL DEFAULT NOW()
+        );
+        CREATE INDEX idx_utility_obs_shellbrain ON utility_observations(memory_id);
+        CREATE INDEX idx_utility_obs_problem ON utility_observations(problem_id);
+        CREATE INDEX idx_utility_obs_created_at ON utility_observations(created_at);
+
+        CREATE TABLE evidence_refs (
+          id TEXT PRIMARY KEY,
+          repo_id TEXT NOT NULL,
+          ref TEXT NOT NULL,
+          created_at TIMESTAMPTZ NOT NULL DEFAULT NOW()
+        );
+        CREATE UNIQUE INDEX uq_evidence_repo_ref ON evidence_refs(repo_id, ref);
+
+        CREATE TABLE memory_evidence (
+          memory_id TEXT NOT NULL REFERENCES memories(id) ON DELETE CASCADE,
+          evidence_id TEXT NOT NULL REFERENCES evidence_refs(id) ON DELETE CASCADE,
+          PRIMARY KEY (memory_id, evidence_id)
+        );
+        CREATE INDEX idx_memory_evidence_evidence ON memory_evidence(evidence_id);
+
+        CREATE TABLE association_edge_evidence (
+          edge_id TEXT NOT NULL REFERENCES association_edges(id) ON DELETE CASCADE,
+          evidence_id TEXT NOT NULL REFERENCES evidence_refs(id) ON DELETE CASCADE,
+          PRIMARY KEY (edge_id, evidence_id)
+        );
+        CREATE INDEX idx_assoc_edge_evidence_evidence ON association_edge_evidence(evidence_id);
+
+        CREATE VIEW current_fact_snapshot AS
+        SELECT m.*
+        FROM memories m
+        WHERE m.kind = 'fact'
+          AND m.archived = FALSE
+          AND NOT EXISTS (
+            SELECT 1 FROM fact_updates fu WHERE fu.old_fact_id = m.id
+          );
+
+        CREATE VIEW global_utility AS
+        SELECT memory_id, AVG(vote) AS utility_mean, COUNT(*) AS observations
+        FROM utility_observations
+        GROUP BY memory_id;
+
+        CREATE VIEW direct_dependency_counts AS
+        SELECT repo_id, from_memory_id AS memory_id, COUNT(*) AS dependency_count
+        FROM association_edges
+        WHERE relation_type = 'depends_on' AND state != 'deprecated'
+        GROUP BY repo_id, from_memory_id;
+
+        CREATE VIEW direct_dependent_counts AS
+        SELECT repo_id, to_memory_id AS memory_id, COUNT(*) AS dependent_count
+        FROM association_edges
+        WHERE relation_type = 'depends_on' AND state != 'deprecated'
+        GROUP BY repo_id, to_memory_id;
+        """
+    )
+
+
+def downgrade() -> None:
+    """This function removes the initial schema, indexes, and derived views."""
+
+    op.execute(
+        """
+        DROP VIEW IF EXISTS direct_dependent_counts;
+        DROP VIEW IF EXISTS direct_dependency_counts;
+        DROP VIEW IF EXISTS global_utility;
+        DROP VIEW IF EXISTS current_fact_snapshot;
+
+        DROP TABLE IF EXISTS association_edge_evidence;
+        DROP TABLE IF EXISTS memory_evidence;
+        DROP TABLE IF EXISTS evidence_refs;
+        DROP TABLE IF EXISTS utility_observations;
+        DROP TABLE IF EXISTS association_observations;
+        DROP TABLE IF EXISTS association_edges;
+        DROP TABLE IF EXISTS fact_updates;
+        DROP TABLE IF EXISTS problem_attempts;
+        DROP TABLE IF EXISTS memory_embeddings;
+        DROP TABLE IF EXISTS session_transfers;
+        DROP TABLE IF EXISTS episode_events;
+        DROP TABLE IF EXISTS episodes;
+        DROP TABLE IF EXISTS memories;
+        """
+    )

app/migrations/versions/20260312_0002_add_hard_invariants.py

@@ -0,0 +1,60 @@
+"""Add hard schema invariants for episodes, problem attempts, and fact updates."""
+
+from alembic import op
+
+
+revision = "20260312_0002"
+down_revision = "20260226_0001"
+branch_labels = None
+depends_on = None
+
+
+def upgrade() -> None:
+    """Apply additional DB-level constraints that encode obvious write invariants."""
+
+    op.execute(
+        """
+        ALTER TABLE episodes
+        ADD CONSTRAINT ck_episodes_ended_after_started
+        CHECK (ended_at IS NULL OR ended_at >= started_at);
+
+        ALTER TABLE session_transfers
+        ADD CONSTRAINT ck_session_transfers_distinct_episodes
+        CHECK (from_episode_id <> to_episode_id);
+
+        ALTER TABLE problem_attempts
+        ADD CONSTRAINT ck_problem_attempts_distinct_memories
+        CHECK (problem_id <> attempt_id);
+
+        ALTER TABLE fact_updates
+        ADD CONSTRAINT ck_fact_updates_distinct_fact_endpoints
+        CHECK (old_fact_id <> new_fact_id);
+
+        ALTER TABLE fact_updates
+        ADD CONSTRAINT ck_fact_updates_change_id_distinct
+        CHECK (change_id <> old_fact_id AND change_id <> new_fact_id);
+        """
+    )
+
+
+def downgrade() -> None:
+    """Remove the added DB-level invariant constraints."""
+
+    op.execute(
+        """
+        ALTER TABLE fact_updates
+        DROP CONSTRAINT IF EXISTS ck_fact_updates_change_id_distinct;
+
+        ALTER TABLE fact_updates
+        DROP CONSTRAINT IF EXISTS ck_fact_updates_distinct_fact_endpoints;
+
+        ALTER TABLE problem_attempts
+        DROP CONSTRAINT IF EXISTS ck_problem_attempts_distinct_memories;
+
+        ALTER TABLE session_transfers
+        DROP CONSTRAINT IF EXISTS ck_session_transfers_distinct_episodes;
+
+        ALTER TABLE episodes
+        DROP CONSTRAINT IF EXISTS ck_episodes_ended_after_started;
+        """
+    )

app/migrations/versions/20260312_0003_drop_create_confidence.py

@@ -0,0 +1,40 @@
+"""Drop create_confidence from memories after removing it from the write contract."""
+
+from alembic import op
+
+from app.periphery.db.models.views import CURRENT_FACT_SNAPSHOT_SQL
+
+
+revision = "20260312_0003"
+down_revision = "20260312_0002"
+branch_labels = None
+depends_on = None
+
+
+def upgrade() -> None:
+    """Remove the obsolete create_confidence column from memories."""
+
+    op.execute(
+        """
+        DROP VIEW IF EXISTS current_fact_snapshot;
+
+        ALTER TABLE memories
+        DROP COLUMN IF EXISTS create_confidence;
+        """
+    )
+    op.execute(CURRENT_FACT_SNAPSHOT_SQL)
+
+
+def downgrade() -> None:
+    """Restore the removed create_confidence column for downgrade compatibility."""
+
+    op.execute(
+        """
+        DROP VIEW IF EXISTS current_fact_snapshot;
+
+        ALTER TABLE memories
+        ADD COLUMN IF NOT EXISTS create_confidence DOUBLE PRECISION
+        CHECK (create_confidence >= 0 AND create_confidence <= 1);
+        """
+    )
+    op.execute(CURRENT_FACT_SNAPSHOT_SQL)

app/migrations/versions/20260313_0004_episode_sync_hardening.py

@@ -0,0 +1,71 @@
+"""Add explicit host session metadata and upstream event dedupe for episodes."""
+
+from alembic import op
+
+
+revision = "20260313_0004"
+down_revision = "20260312_0003"
+branch_labels = None
+depends_on = None
+
+
+def upgrade() -> None:
+    """Add host-app identity and upstream event keys for episodic sync."""
+
+    op.execute(
+        """
+        ALTER TABLE episodes
+        ADD COLUMN host_app TEXT;
+
+        UPDATE episodes
+        SET host_app = CASE
+          WHEN thread_id LIKE 'codex:%' THEN 'codex'
+          WHEN thread_id LIKE 'claude_code:%' THEN 'claude_code'
+          ELSE 'unknown'
+        END
+        WHERE host_app IS NULL;
+
+        ALTER TABLE episodes
+        ALTER COLUMN host_app SET NOT NULL;
+
+        ALTER TABLE episode_events
+        ADD COLUMN host_event_key TEXT;
+
+        UPDATE episode_events
+        SET host_event_key = 'legacy:' || id
+        WHERE host_event_key IS NULL;
+
+        ALTER TABLE episode_events
+        ALTER COLUMN host_event_key SET NOT NULL;
+
+        DROP INDEX IF EXISTS idx_episodes_repo_thread;
+
+        ALTER TABLE episodes
+        ADD CONSTRAINT uq_episodes_repo_thread UNIQUE (repo_id, thread_id);
+
+        ALTER TABLE episode_events
+        ADD CONSTRAINT uq_episode_events_host_event_key UNIQUE (episode_id, host_event_key);
+        """
+    )
+
+
+def downgrade() -> None:
+    """Remove episode sync hardening columns and constraints."""
+
+    op.execute(
+        """
+        ALTER TABLE episode_events
+        DROP CONSTRAINT IF EXISTS uq_episode_events_host_event_key;
+
+        ALTER TABLE episodes
+        DROP CONSTRAINT IF EXISTS uq_episodes_repo_thread;
+
+        CREATE INDEX IF NOT EXISTS idx_episodes_repo_thread ON episodes(repo_id, thread_id);
+
+        ALTER TABLE episode_events
+        DROP COLUMN IF EXISTS host_event_key;
+
+        ALTER TABLE episodes
+        DROP COLUMN IF EXISTS host_app;
+        """
+    )

app/migrations/versions/20260313_0005_evidence_episode_event_refs.py

@@ -0,0 +1,45 @@
+"""Attach evidence references directly to stored episode events."""
+
+from alembic import op
+
+
+revision = "20260313_0005"
+down_revision = "20260313_0004"
+branch_labels = None
+depends_on = None
+
+
+def upgrade() -> None:
+    """Add episode_event-backed evidence references while preserving legacy ref strings."""
+
+    op.execute(
+        """
+        ALTER TABLE evidence_refs
+        ADD COLUMN episode_event_id TEXT REFERENCES episode_events(id);
+
+        UPDATE evidence_refs AS er
+        SET episode_event_id = er.ref
+        FROM episode_events AS ee
+        JOIN episodes AS ep ON ep.id = ee.episode_id
+        WHERE er.episode_event_id IS NULL
+          AND er.ref = ee.id
+          AND er.repo_id = ep.repo_id;
+
+        ALTER TABLE evidence_refs
+        ADD CONSTRAINT uq_evidence_repo_episode_event UNIQUE (repo_id, episode_event_id);
+        """
+    )
+
+
+def downgrade() -> None:
+    """Remove episode-event-backed evidence reference storage."""
+
+    op.execute(
+        """
+        ALTER TABLE evidence_refs
+        DROP CONSTRAINT IF EXISTS uq_evidence_repo_episode_event;
+
+        ALTER TABLE evidence_refs
+        DROP COLUMN IF EXISTS episode_event_id;
+        """
+    )

app/migrations/versions/20260318_0006_usage_telemetry_schema.py

@@ -0,0 +1,175 @@
+"""Create low-overhead usage telemetry storage and analytics views."""
+
+from alembic import op
+
+from app.periphery.db.models.views import (
+    USAGE_COMMAND_DAILY_SQL,
+    USAGE_MEMORY_RETRIEVAL_SQL,
+    USAGE_SESSION_PROTOCOL_SQL,
+    USAGE_SYNC_HEALTH_SQL,
+    USAGE_WRITE_EFFECTS_SQL,
+)
+
+revision = "20260318_0006"
+down_revision = "20260313_0005"
+branch_labels = None
+depends_on = None
+
+
+def upgrade() -> None:
+    """Create telemetry tables, indexes, and derived analytics views."""
+
+    op.execute(
+        """
+        CREATE TABLE operation_invocations (
+          id TEXT PRIMARY KEY,
+          command TEXT NOT NULL CHECK (command IN ('read', 'create', 'update', 'events')),
+          repo_id TEXT NOT NULL,
+          repo_root TEXT NOT NULL,
+          no_sync BOOLEAN NOT NULL DEFAULT FALSE,
+          selected_host_app TEXT,
+          selected_host_session_key TEXT,
+          selected_thread_id TEXT,
+          selected_episode_id TEXT,
+          matching_candidate_count INTEGER NOT NULL DEFAULT 0 CHECK (matching_candidate_count >= 0),
+          selection_ambiguous BOOLEAN NOT NULL DEFAULT FALSE,
+          outcome TEXT NOT NULL CHECK (outcome IN ('ok', 'error')),
+          error_stage TEXT,
+          error_code TEXT,
+          error_message TEXT,
+          total_latency_ms INTEGER NOT NULL CHECK (total_latency_ms >= 0),
+          poller_start_attempted BOOLEAN NOT NULL DEFAULT FALSE,
+          poller_started BOOLEAN NOT NULL DEFAULT FALSE,
+          created_at TIMESTAMPTZ NOT NULL DEFAULT NOW()
+        );
+        CREATE INDEX idx_operation_invocations_repo_created_at
+          ON operation_invocations(repo_id, created_at);
+        CREATE INDEX idx_operation_invocations_command_created_at
+          ON operation_invocations(command, created_at);
+        CREATE INDEX idx_operation_invocations_thread_created_at
+          ON operation_invocations(selected_thread_id, created_at)
+          WHERE selected_thread_id IS NOT NULL;
+
+        CREATE TABLE read_invocation_summaries (
+          invocation_id TEXT PRIMARY KEY REFERENCES operation_invocations(id) ON DELETE CASCADE,
+          query_text TEXT NOT NULL,
+          mode TEXT NOT NULL,
+          requested_limit INTEGER,
+          effective_limit INTEGER NOT NULL CHECK (effective_limit >= 0),
+          include_global BOOLEAN,
+          kinds_filter JSONB,
+          direct_count INTEGER NOT NULL CHECK (direct_count >= 0),
+          explicit_related_count INTEGER NOT NULL CHECK (explicit_related_count >= 0),
+          implicit_related_count INTEGER NOT NULL CHECK (implicit_related_count >= 0),
+          total_returned INTEGER NOT NULL CHECK (total_returned >= 0),
+          zero_results BOOLEAN NOT NULL,
+          created_at TIMESTAMPTZ NOT NULL DEFAULT NOW()
+        );
+
+        CREATE TABLE read_result_items (
+          invocation_id TEXT NOT NULL REFERENCES operation_invocations(id) ON DELETE CASCADE,
+          ordinal INTEGER NOT NULL CHECK (ordinal > 0),
+          memory_id TEXT NOT NULL,
+          kind TEXT NOT NULL,
+          section TEXT NOT NULL,
+          priority INTEGER NOT NULL CHECK (priority > 0),
+          why_included TEXT NOT NULL,
+          anchor_memory_id TEXT,
+          relation_type TEXT,
+          PRIMARY KEY (invocation_id, ordinal)
+        );
+        CREATE INDEX idx_read_result_items_memory_invocation
+          ON read_result_items(memory_id, invocation_id);
+
+        CREATE TABLE write_invocation_summaries (
+          invocation_id TEXT PRIMARY KEY REFERENCES operation_invocations(id) ON DELETE CASCADE,
+          operation_command TEXT NOT NULL CHECK (operation_command IN ('create', 'update')),
+          target_memory_id TEXT NOT NULL,
+          target_kind TEXT,
+          update_type TEXT,
+          scope TEXT,
+          evidence_ref_count INTEGER NOT NULL DEFAULT 0 CHECK (evidence_ref_count >= 0),
+          planned_effect_count INTEGER NOT NULL CHECK (planned_effect_count >= 0),
+          created_memory_count INTEGER NOT NULL DEFAULT 0 CHECK (created_memory_count >= 0),
+          archived_memory_count INTEGER NOT NULL DEFAULT 0 CHECK (archived_memory_count >= 0),
+          utility_observation_count INTEGER NOT NULL DEFAULT 0 CHECK (utility_observation_count >= 0),
+          association_effect_count INTEGER NOT NULL DEFAULT 0 CHECK (association_effect_count >= 0),
+          fact_update_count INTEGER NOT NULL DEFAULT 0 CHECK (fact_update_count >= 0),
+          created_at TIMESTAMPTZ NOT NULL DEFAULT NOW()
+        );
+
+        CREATE TABLE write_effect_items (
+          invocation_id TEXT NOT NULL REFERENCES operation_invocations(id) ON DELETE CASCADE,
+          ordinal INTEGER NOT NULL CHECK (ordinal > 0),
+          effect_type TEXT NOT NULL,
+          repo_id TEXT NOT NULL,
+          primary_memory_id TEXT,
+          secondary_memory_id TEXT,
+          params_json JSONB NOT NULL DEFAULT '{}'::jsonb,
+          PRIMARY KEY (invocation_id, ordinal)
+        );
+        CREATE INDEX idx_write_effect_items_repo_effect_invocation
+          ON write_effect_items(repo_id, effect_type, invocation_id);
+
+        CREATE TABLE episode_sync_runs (
+          id TEXT PRIMARY KEY,
+          source TEXT NOT NULL CHECK (source IN ('events_inline', 'poller')),
+          invocation_id TEXT REFERENCES operation_invocations(id) ON DELETE SET NULL,
+          repo_id TEXT NOT NULL,
+          host_app TEXT NOT NULL,
+          host_session_key TEXT NOT NULL,
+          thread_id TEXT NOT NULL,
+          episode_id TEXT,
+          transcript_path TEXT,
+          outcome TEXT NOT NULL CHECK (outcome IN ('ok', 'error')),
+          error_stage TEXT,
+          error_message TEXT,
+          duration_ms INTEGER NOT NULL CHECK (duration_ms >= 0),
+          imported_event_count INTEGER NOT NULL DEFAULT 0 CHECK (imported_event_count >= 0),
+          total_event_count INTEGER NOT NULL DEFAULT 0 CHECK (total_event_count >= 0),
+          user_event_count INTEGER NOT NULL DEFAULT 0 CHECK (user_event_count >= 0),
+          assistant_event_count INTEGER NOT NULL DEFAULT 0 CHECK (assistant_event_count >= 0),
+          tool_event_count INTEGER NOT NULL DEFAULT 0 CHECK (tool_event_count >= 0),
+          system_event_count INTEGER NOT NULL DEFAULT 0 CHECK (system_event_count >= 0),
+          created_at TIMESTAMPTZ NOT NULL DEFAULT NOW()
+        );
+        CREATE INDEX idx_episode_sync_runs_repo_host_created_at
+          ON episode_sync_runs(repo_id, host_app, created_at);
+        CREATE INDEX idx_episode_sync_runs_thread_created_at
+          ON episode_sync_runs(thread_id, created_at);
+
+        CREATE TABLE episode_sync_tool_types (
+          sync_run_id TEXT NOT NULL REFERENCES episode_sync_runs(id) ON DELETE CASCADE,
+          tool_type TEXT NOT NULL,
+          event_count INTEGER NOT NULL CHECK (event_count >= 0),
+          PRIMARY KEY (sync_run_id, tool_type)
+        );
+        """
+    )
+    op.execute(USAGE_COMMAND_DAILY_SQL)
+    op.execute(USAGE_MEMORY_RETRIEVAL_SQL)
+    op.execute(USAGE_WRITE_EFFECTS_SQL)
+    op.execute(USAGE_SYNC_HEALTH_SQL)
+    op.execute(USAGE_SESSION_PROTOCOL_SQL)
+
+
+def downgrade() -> None:
+    """Drop telemetry views, indexes, and tables."""
+
+    op.execute(
+        """
+        DROP VIEW IF EXISTS usage_session_protocol;
+        DROP VIEW IF EXISTS usage_sync_health;
+        DROP VIEW IF EXISTS usage_write_effects;
+        DROP VIEW IF EXISTS usage_memory_retrieval;
+        DROP VIEW IF EXISTS usage_command_daily;
+
+        DROP TABLE IF EXISTS episode_sync_tool_types;
+        DROP TABLE IF EXISTS episode_sync_runs;
+        DROP TABLE IF EXISTS write_effect_items;
+        DROP TABLE IF EXISTS write_invocation_summaries;
+        DROP TABLE IF EXISTS read_result_items;
+        DROP TABLE IF EXISTS read_invocation_summaries;
+        DROP TABLE IF EXISTS operation_invocations;
+        """
+    )

app/migrations/versions/20260319_0007_identity_session_guidance.py

@@ -0,0 +1,49 @@
+"""Extend telemetry storage with caller identity and guidance metadata."""
+
+from alembic import op
+
+
+revision = "20260319_0007"
+down_revision = "20260318_0006"
+branch_labels = None
+depends_on = None
+
+
+def upgrade() -> None:
+    """Add identity and guidance columns to operation telemetry."""
+
+    op.execute(
+        """
+        ALTER TABLE operation_invocations
+          ADD COLUMN IF NOT EXISTS caller_id TEXT;
+
+        ALTER TABLE operation_invocations
+          ADD COLUMN IF NOT EXISTS caller_trust_level TEXT;
+
+        ALTER TABLE operation_invocations
+          ADD COLUMN IF NOT EXISTS identity_failure_code TEXT;
+
+        ALTER TABLE operation_invocations
+          ADD COLUMN IF NOT EXISTS guidance_codes JSONB NOT NULL DEFAULT '[]'::jsonb;
+        """
+    )
+
+
+def downgrade() -> None:
+    """Drop identity and guidance columns from operation telemetry."""
+
+    op.execute(
+        """
+        ALTER TABLE operation_invocations
+          DROP COLUMN IF EXISTS guidance_codes;
+
+        ALTER TABLE operation_invocations
+          DROP COLUMN IF EXISTS identity_failure_code;
+
+        ALTER TABLE operation_invocations
+          DROP COLUMN IF EXISTS caller_trust_level;
+
+        ALTER TABLE operation_invocations
+          DROP COLUMN IF EXISTS caller_id;
+        """
+    )