agentloop-profiler 0.1.0__py3-none-any.whl

agentloop/metrics.py

@@ -0,0 +1,342 @@
+from __future__ import annotations
+
+from collections import Counter
+from collections.abc import Mapping
+from typing import Any
+
+from agentloop.costs import CostEstimate, PricingTable, estimate_cost, load_pricing_table
+from agentloop.graph import ExecutionGraph
+from agentloop.judgments import read_judgments
+from agentloop.operations import operation_counts, operation_kind
+from agentloop.parallelism import parallelization_candidates
+from agentloop.rules import AnalysisContext, run_rules
+from agentloop.semantic_waste import read_semantic_waste
+from agentloop.structured_quality import decision_span_count, read_quality_evidence
+from agentloop.timing import cumulative_span_time_ms, elapsed_runtime_ms
+from agentloop.tokens import (
+    describe_token_status,
+    provenance_counts,
+    provenance_grade,
+    token_status,
+)
+from agentloop.workflow_types import stage_summary, workflow_summary
+
+
+def build_report(trace: Any, *, _aggregate_only: bool = False) -> dict[str, Any]:
+    from agentloop.retention import read_retention, retained_report
+
+    retained = retained_report(trace)
+    if retained is not None:
+        return retained
+    events = trace.events
+    model_events = [e for e in events if e.event_type == "model_call"]
+    tool_events = [e for e in events if e.event_type == "tool_call"]
+    retry_events = [e for e in events if e.event_type == "retry"]
+
+    repeated = repeated_context_stats([e for e in model_events if operation_kind(e) == "model"])
+    parallel = [] if _aggregate_only else parallelism_opportunities(events)
+    cumulative_time = cumulative_span_time_ms(events)
+    cost = cost_breakdown(model_events)
+    tokens = token_breakdown(model_events)
+
+    report = {
+        "run_id": trace.run_id,
+        "name": trace.name,
+        "event_count": len(events),
+        "operation_counts": operation_counts(events),
+        "model_call_count": len(model_events),
+        "tool_call_count": len(tool_events),
+        "retry_count": len(retry_events),
+        "total_runtime_ms": round(elapsed_runtime_ms(trace), 3),
+        "cumulative_span_time_ms": round(cumulative_time, 3),
+        "model_time_ms": round(sum(e.duration_ms for e in model_events), 3),
+        "tool_time_ms": round(sum(e.duration_ms for e in tool_events), 3),
+        "retry_time_ms": round(sum(e.duration_ms for e in retry_events), 3),
+        "input_tokens": sum(e.input_tokens for e in model_events),
+        "output_tokens": sum(e.output_tokens for e in model_events),
+        # How exact those two totals are. Only trust them as a measurement when
+        # `token_status` is "exact" (or "empty") — anything else means at least
+        # one model call approximated its counts, did not have them, or predates
+        # provenance. See agentloop/tokens.py and docs/TRACE_SCHEMA.md.
+        "token_status": tokens["token_status"],
+        "token_provenance_counts": tokens["token_provenance_counts"],
+        # Sum of *known* costs only (calculated + provider-reported). A model with
+        # no known rate contributes nothing here rather than a fabricated rate.
+        # `cost_status` and `cost_breakdown` record whether that number is a
+        # complete measurement or a lower bound, so consumers reading the flat
+        # field can tell. Only trust the total as exact when cost_status is
+        # "complete" (or "empty"). See docs/PRICING.md.
+        "estimated_cost_usd": cost["known_cost_usd"],
+        "cost_status": cost["cost_status"],
+        "cost_breakdown": cost,
+        "repeated_context_tokens": repeated["repeated_context_tokens"],
+        "repeated_context_ratio": repeated["repeated_context_ratio"],
+        "parallelism_opportunities": parallel,
+        "recommendations": [],
+        "events": [] if _aggregate_only else [e.to_dict() for e in events],
+    }
+    from agentloop.interoperability.evidence import qualify_report
+
+    qualify_report(trace, report)
+    from agentloop.integrations.harbor.trial_evidence import qualify_trial_report
+
+    qualify_trial_report(trace, report)
+    from agentloop.integrations.omnigent.evidence import qualify_report as qualify_omnigent_report
+
+    qualify_omnigent_report(trace, report)
+    if _aggregate_only:
+        return report
+    execution = workflow_summary(getattr(trace, "metadata", {}))
+    if execution is not None:
+        report["execution"] = execution
+    stages = {event.event_id: stage_summary(event) for event in events}
+    stages = {key: value for key, value in stages.items() if value is not None}
+    if stages:
+        report["stages"] = stages
+    quality = read_quality_evidence(trace)
+    if quality is not None:
+        report["quality_evidence"] = quality
+        report["quality_score"] = quality["score"]
+        report["decision_count"] = decision_span_count(trace)
+        report["error_span_count"] = sum(event.status == "error" for event in events)
+        report["decision_count_basis"] = "recorded_classifier_or_rule_spans"
+    judgments = read_judgments(trace)
+    if judgments is not None:
+        report["semantic_judgments"] = judgments
+        report["evidence_categories"] = {
+            "observed_facts": "Recorded spans, statuses, durations and usage with their source provenance.",
+            "deterministic_inference": "Finding rules and savings estimates; assumptions still require validation.",
+            "semantic_judgments": "Explicit offline judge answers; separate from observed facts and task quality.",
+        }
+    semantic_waste = read_semantic_waste(trace, judgments=judgments)
+    if semantic_waste is not None:
+        report["semantic_waste"] = semantic_waste
+        report.setdefault(
+            "evidence_categories",
+            {
+                "observed_facts": "Recorded spans, statuses, durations and usage with their source provenance.",
+                "deterministic_inference": "Finding rules and savings estimates; assumptions still require validation.",
+                "semantic_judgments": "Explicit offline judge answers; separate from observed facts and task quality.",
+            },
+        )
+    candidates, errors = run_rules(
+        AnalysisContext(report=report, graph=ExecutionGraph.from_trace(trace))
+    )
+    report["finding_candidates"] = [candidate.to_dict() for candidate in candidates]
+    report["rule_errors"] = errors
+    report["analysis_complete"] = not errors
+    report["recommendations"] = [
+        {
+            "title": item.title,
+            "description": item.why,
+            "rule_id": item.rule_id,
+            "rule_version": item.rule_version,
+        }
+        for item in candidates
+    ]
+    if errors:
+        report["recommendations"].append(
+            {
+                "title": "Analysis incomplete",
+                "description": "Some finding rules failed: "
+                + ", ".join(item["rule_id"] for item in errors),
+            }
+        )
+    if not report["recommendations"]:
+        report["recommendations"] = [
+            {
+                "title": "No major pattern detected",
+                "description": "Collect more traces for stronger recommendations.",
+            }
+        ]
+    retention = read_retention(trace)
+    if retention is not None:
+        report["retention"] = retention
+    return report
+
+
+def _event_cost_estimate(event: Any, pricing: PricingTable) -> CostEstimate:
+    """Estimate one model call's cost, reading provider metadata from the event.
+
+    Provider, cached-input tokens, billing mode, and any provider-reported cost
+    ride in ``event.metadata`` (a free-form field already in the event schema),
+    so this stays compatible with existing serialized traces — a trace without
+    these keys simply falls back to model-name resolution.
+
+    Metadata is untrusted: a non-finite/negative reported cost (which would raise
+    from :func:`estimate_cost`) is caught and turned into an ``unknown`` estimate
+    with an ``invalid_metadata`` reason rather than crashing report construction
+    or fabricating a number.
+    """
+    try:
+        raw_metadata = getattr(event, "metadata", None)
+        if raw_metadata is None:
+            metadata: Mapping[str, Any] = {}
+        elif isinstance(raw_metadata, Mapping):
+            metadata = raw_metadata
+        else:
+            raise ValueError("metadata must be a mapping")
+        if getattr(event, "token_provenance", None) == "external_reported" or (
+            metadata.get("external_evidence_schema") == "1.0"
+        ):
+            return CostEstimate(
+                state="unknown",
+                amount_usd=None,
+                model=event.model,
+                provider=None,
+                pricing_source=None,
+                pricing_as_of=None,
+                input_tokens=event.input_tokens,
+                output_tokens=event.output_tokens,
+                cached_input_tokens=0,
+                unknown_reason="external_usage_not_provider_accounting",
+            )
+        provider = metadata.get("provider")
+        billing_mode = metadata.get("billing_mode")
+        if provider is not None and not isinstance(provider, str):
+            raise ValueError("metadata provider must be a string")
+        if billing_mode is not None and not isinstance(billing_mode, str):
+            raise ValueError("metadata billing_mode must be a string")
+
+        reported = metadata.get("provider_reported_cost_usd", metadata.get("cost_usd"))
+        return estimate_cost(
+            event.model,
+            event.input_tokens,
+            event.output_tokens,
+            provider=provider,
+            cached_input_tokens=metadata.get("cached_input_tokens", 0),
+            billing_mode=billing_mode,
+            provider_reported_cost_usd=None if reported is None else float(reported),
+            pricing=pricing,
+        )
+    except (AttributeError, OverflowError, TypeError, ValueError):
+        raw_metadata = getattr(event, "metadata", None)
+        metadata = raw_metadata if isinstance(raw_metadata, Mapping) else {}
+        provider = metadata.get("provider")
+        provider = provider if isinstance(provider, str) else None
+        return CostEstimate(
+            state="unknown",
+            amount_usd=None,
+            model=event.model,
+            provider=provider,
+            pricing_source=None,
+            pricing_as_of=None,
+            input_tokens=event.input_tokens,
+            output_tokens=event.output_tokens,
+            cached_input_tokens=0,
+            unknown_reason="invalid_metadata",
+        )
+
+
+def cost_breakdown(model_events: list[Any], pricing: PricingTable | None = None) -> dict[str, Any]:
+    """Aggregate per-call cost estimates, distinguishing the three cost kinds.
+
+    Returns known totals split by source (calculated vs. provider-reported), a
+    count and list of model calls whose pricing was unavailable, and the
+    provenance (sources and ``as_of`` dates) behind the calculated portion, so a
+    report can show exactly how complete and how current its cost number is.
+    """
+    table = pricing if pricing is not None or not model_events else load_pricing_table()
+    estimates = [_event_cost_estimate(event, table) for event in model_events]
+
+    calculated = round(sum(e.amount_usd or 0.0 for e in estimates if e.state == "calculated"), 6)
+    provider_reported = round(
+        sum(e.amount_usd or 0.0 for e in estimates if e.state == "provider_reported"), 6
+    )
+    unknown = [e for e in estimates if e.state == "unknown"]
+    sources = sorted(
+        {e.pricing_source for e in estimates if e.state == "calculated" and e.pricing_source}
+    )
+    as_of = sorted(
+        {e.pricing_as_of for e in estimates if e.state == "calculated" and e.pricing_as_of}
+    )
+    unknown_models = sorted({str(e.model) for e in unknown})
+    unknown_reasons = sorted({e.unknown_reason for e in unknown if e.unknown_reason})
+
+    return {
+        "cost_status": _cost_status(len(estimates), len(unknown)),
+        # A calculated cost is a rate multiplied by a token count, so it is only
+        # as exact as that count. Carrying the token basis alongside the cost
+        # stops a dollar amount derived from word estimates from reading as an
+        # exact calculated cost (issue #133).
+        "token_status": token_status(model_events),
+        "known_cost_usd": round(calculated + provider_reported, 6),
+        "calculated_usd": calculated,
+        "provider_reported_usd": provider_reported,
+        "priced_model_call_count": len(estimates) - len(unknown),
+        "unavailable_model_call_count": len(unknown),
+        "has_unknown_cost": bool(unknown),
+        "pricing_sources": sources,
+        "pricing_as_of": as_of,
+        "unknown_models": unknown_models,
+        "unknown_reasons": unknown_reasons,
+        "model_calls": [e.to_dict() for e in estimates],
+    }
+
+
+def token_breakdown(model_events: list[Any]) -> dict[str, Any]:
+    """Summarize how exact a trace's token counts are, and why.
+
+    The counts in ``input_tokens``/``output_tokens`` mix provider-reported usage
+    with a whitespace word-count fallback, so a total on its own cannot say
+    whether it is a measurement. This returns the aggregate
+    :func:`agentloop.tokens.token_status` plus the per-provenance call counts
+    behind it, so a report can show exactly how its token number was obtained.
+    """
+
+    status = token_status(model_events)
+    return {
+        "token_status": status,
+        "token_status_detail": describe_token_status(status),
+        "token_provenance_counts": provenance_counts(model_events),
+        "exact_token_call_count": sum(
+            1
+            for e in model_events
+            if provenance_grade(getattr(e, "token_provenance", None)) == "exact"
+        ),
+        "estimated_token_call_count": sum(
+            1
+            for e in model_events
+            if provenance_grade(getattr(e, "token_provenance", None)) == "estimated"
+        ),
+    }
+
+
+def _cost_status(total_calls: int, unknown_calls: int) -> str:
+    """Summarize how complete a trace's cost total is.
+
+    - ``empty``    — no model calls, so there is no cost to know.
+    - ``complete`` — every model call had a known (calculated/reported) cost.
+    - ``unknown``  — no model call could be priced.
+    - ``partial``  — some priced, some not; the total is a lower bound.
+
+    Consumers should treat anything other than ``complete``/``empty`` as "do not
+    present the cost total or its deltas as a full, comparable measurement."
+    """
+    if total_calls == 0:
+        return "empty"
+    if unknown_calls == 0:
+        return "complete"
+    if unknown_calls == total_calls:
+        return "unknown"
+    return "partial"
+
+
+def repeated_context_stats(model_events: list[Any]) -> dict[str, Any]:
+    prefixes = []
+    total_tokens = sum(e.input_tokens for e in model_events)
+    for event in model_events:
+        words = (event.input_text or "").split()
+        if words:
+            prefixes.append((" ".join(words[:80]), min(len(words), 80)))
+    counts = Counter(prefix for prefix, _ in prefixes)
+    repeated_tokens = sum(tokens for prefix, tokens in prefixes if counts[prefix] > 1)
+    avoidable = max(0, repeated_tokens // 2)
+    ratio = avoidable / total_tokens if total_tokens else 0.0
+    return {"repeated_context_tokens": avoidable, "repeated_context_ratio": round(ratio, 4)}
+
+
+def parallelism_opportunities(tool_events: list[Any]) -> list[dict[str, Any]]:
+    return [
+        {"tool_name": group["name"], **group} for group in parallelization_candidates(tool_events)
+    ]

agentloop/migrations.py

@@ -0,0 +1,303 @@
+"""Versioned schema migrations shared by :mod:`agentloop.store`'s two backends.
+
+Each :class:`Migration` carries dialect-specific, idempotent SQL statements.
+Idempotency (``IF NOT EXISTS`` / ``ON CONFLICT ... DO NOTHING``) lets concurrent
+``init()`` calls apply the same pending migration twice without corrupting state
+or racing on `schema_migrations` bookkeeping, which stands in for a real
+distributed lock that neither backend otherwise provides here.
+
+A fresh install and an existing pre-migration database both start with no rows
+in `schema_migrations`; migration 0001 reproduces the exact schema `init()`
+used to create inline, so both converge on the same structure.
+"""
+
+from __future__ import annotations
+
+from dataclasses import dataclass
+
+
+class MigrationError(RuntimeError):
+    """Raised when a migration statement fails to apply."""
+
+
+@dataclass(frozen=True)
+class Migration:
+    version: int
+    name: str
+    sqlite_statements: tuple[str, ...]
+    postgres_statements: tuple[str, ...]
+
+
+_BASELINE_SQLITE = (
+    """
+    CREATE TABLE IF NOT EXISTS projects (
+        project_id TEXT PRIMARY KEY,
+        created_at TEXT DEFAULT CURRENT_TIMESTAMP
+    )
+    """,
+    """
+    CREATE TABLE IF NOT EXISTS api_keys (
+        key_hash TEXT PRIMARY KEY,
+        project_id TEXT NOT NULL,
+        name TEXT NOT NULL,
+        prefix TEXT NOT NULL,
+        created_at TEXT DEFAULT CURRENT_TIMESTAMP,
+        last_used_at TEXT,
+        FOREIGN KEY(project_id) REFERENCES projects(project_id)
+    )
+    """,
+    """
+    CREATE TABLE IF NOT EXISTS traces (
+        run_id TEXT PRIMARY KEY,
+        project_id TEXT NOT NULL,
+        name TEXT NOT NULL,
+        started_at TEXT,
+        payload_json TEXT NOT NULL,
+        total_runtime_ms REAL DEFAULT 0,
+        estimated_cost_usd REAL DEFAULT 0,
+        model_call_count INTEGER DEFAULT 0,
+        tool_call_count INTEGER DEFAULT 0,
+        retry_count INTEGER DEFAULT 0,
+        created_at TEXT DEFAULT CURRENT_TIMESTAMP,
+        FOREIGN KEY(project_id) REFERENCES projects(project_id)
+    )
+    """,
+    """
+    CREATE TABLE IF NOT EXISTS usage_events (
+        id INTEGER PRIMARY KEY AUTOINCREMENT,
+        project_id TEXT NOT NULL,
+        run_id TEXT NOT NULL,
+        total_runtime_ms REAL DEFAULT 0,
+        estimated_cost_usd REAL DEFAULT 0,
+        input_tokens INTEGER DEFAULT 0,
+        output_tokens INTEGER DEFAULT 0,
+        model_call_count INTEGER DEFAULT 0,
+        tool_call_count INTEGER DEFAULT 0,
+        retry_count INTEGER DEFAULT 0,
+        created_at TEXT DEFAULT CURRENT_TIMESTAMP
+    )
+    """,
+    """
+    CREATE TABLE IF NOT EXISTS trace_findings (
+        project_id TEXT NOT NULL,
+        run_id TEXT NOT NULL,
+        finding_id TEXT NOT NULL,
+        type TEXT NOT NULL,
+        severity TEXT NOT NULL,
+        title TEXT NOT NULL,
+        confidence TEXT NOT NULL,
+        patchable INTEGER DEFAULT 0,
+        status TEXT DEFAULT 'detected',
+        estimated_latency_savings_ms REAL DEFAULT 0,
+        estimated_cost_savings_usd REAL DEFAULT 0,
+        payload_json TEXT NOT NULL,
+        created_at TEXT DEFAULT CURRENT_TIMESTAMP,
+        updated_at TEXT DEFAULT CURRENT_TIMESTAMP,
+        PRIMARY KEY(project_id, run_id, finding_id),
+        FOREIGN KEY(project_id) REFERENCES projects(project_id),
+        FOREIGN KEY(run_id) REFERENCES traces(run_id)
+    )
+    """,
+    "INSERT OR IGNORE INTO projects(project_id) VALUES ('default')",
+)
+
+_BASELINE_POSTGRES = (
+    "CREATE TABLE IF NOT EXISTS projects ("
+    "project_id TEXT PRIMARY KEY, created_at TIMESTAMPTZ DEFAULT now())",
+    "CREATE TABLE IF NOT EXISTS api_keys ("
+    "key_hash TEXT PRIMARY KEY, project_id TEXT NOT NULL REFERENCES projects(project_id), "
+    "name TEXT NOT NULL, prefix TEXT NOT NULL, created_at TIMESTAMPTZ DEFAULT now(), "
+    "last_used_at TIMESTAMPTZ)",
+    "CREATE TABLE IF NOT EXISTS traces ("
+    "run_id TEXT PRIMARY KEY, project_id TEXT NOT NULL REFERENCES projects(project_id), "
+    "name TEXT NOT NULL, started_at TEXT, payload_json JSONB NOT NULL, "
+    "total_runtime_ms DOUBLE PRECISION DEFAULT 0, estimated_cost_usd DOUBLE PRECISION DEFAULT 0, "
+    "model_call_count INTEGER DEFAULT 0, tool_call_count INTEGER DEFAULT 0, "
+    "retry_count INTEGER DEFAULT 0, created_at TIMESTAMPTZ DEFAULT now())",
+    "CREATE TABLE IF NOT EXISTS usage_events ("
+    "id BIGSERIAL PRIMARY KEY, project_id TEXT NOT NULL, run_id TEXT NOT NULL, "
+    "total_runtime_ms DOUBLE PRECISION DEFAULT 0, estimated_cost_usd DOUBLE PRECISION DEFAULT 0, "
+    "input_tokens INTEGER DEFAULT 0, output_tokens INTEGER DEFAULT 0, "
+    "model_call_count INTEGER DEFAULT 0, tool_call_count INTEGER DEFAULT 0, "
+    "retry_count INTEGER DEFAULT 0, created_at TIMESTAMPTZ DEFAULT now())",
+    "CREATE TABLE IF NOT EXISTS trace_findings ("
+    "project_id TEXT NOT NULL REFERENCES projects(project_id), "
+    "run_id TEXT NOT NULL REFERENCES traces(run_id), finding_id TEXT NOT NULL, "
+    "type TEXT NOT NULL, severity TEXT NOT NULL, title TEXT NOT NULL, confidence TEXT NOT NULL, "
+    "patchable BOOLEAN DEFAULT false, status TEXT DEFAULT 'detected', "
+    "estimated_latency_savings_ms DOUBLE PRECISION DEFAULT 0, "
+    "estimated_cost_savings_usd DOUBLE PRECISION DEFAULT 0, payload_json JSONB NOT NULL, "
+    "created_at TIMESTAMPTZ DEFAULT now(), updated_at TIMESTAMPTZ DEFAULT now(), "
+    "PRIMARY KEY(project_id, run_id, finding_id))",
+    "INSERT INTO projects(project_id) VALUES ('default') ON CONFLICT DO NOTHING",
+)
+
+# usage_events had no uniqueness constraint, so retried save_trace() calls appended
+# a new row per retry instead of updating one. De-duplicate existing data (keep the
+# most recent row per project/run) before the constraint can be added, or the
+# index creation fails on any store that already has duplicates.
+_DEDUPE_AND_CONSTRAIN_USAGE_EVENTS = (
+    "DELETE FROM usage_events WHERE id NOT IN "
+    "(SELECT MAX(id) FROM usage_events GROUP BY project_id, run_id)",
+    "CREATE UNIQUE INDEX IF NOT EXISTS ux_usage_events_project_run "
+    "ON usage_events(project_id, run_id)",
+)
+
+_PAGINATION_INDEXES = (
+    "CREATE INDEX IF NOT EXISTS ix_traces_project_created "
+    "ON traces(project_id, created_at, run_id)",
+    "CREATE INDEX IF NOT EXISTS ix_trace_findings_project_status_updated "
+    "ON trace_findings(project_id, status, updated_at, run_id, finding_id)",
+)
+
+_COST_COMPLETENESS_SQLITE = (
+    "ALTER TABLE traces ADD COLUMN cost_status TEXT NOT NULL DEFAULT 'complete'",
+    "ALTER TABLE traces ADD COLUMN priced_model_call_count INTEGER NOT NULL DEFAULT 0",
+    "ALTER TABLE traces ADD COLUMN unavailable_model_call_count INTEGER NOT NULL DEFAULT 0",
+    "ALTER TABLE usage_events ADD COLUMN cost_status TEXT NOT NULL DEFAULT 'complete'",
+    "ALTER TABLE usage_events ADD COLUMN priced_model_call_count INTEGER NOT NULL DEFAULT 0",
+    "ALTER TABLE usage_events ADD COLUMN unavailable_model_call_count INTEGER NOT NULL DEFAULT 0",
+    "UPDATE traces SET cost_status = CASE WHEN model_call_count = 0 THEN 'empty' ELSE 'complete' END, "
+    "priced_model_call_count = model_call_count, unavailable_model_call_count = 0",
+    "UPDATE usage_events SET cost_status = CASE WHEN model_call_count = 0 THEN 'empty' ELSE 'complete' END, "
+    "priced_model_call_count = model_call_count, unavailable_model_call_count = 0",
+)
+
+_COST_COMPLETENESS_POSTGRES = (
+    "ALTER TABLE traces ADD COLUMN IF NOT EXISTS cost_status TEXT NOT NULL DEFAULT 'complete'",
+    "ALTER TABLE traces ADD COLUMN IF NOT EXISTS priced_model_call_count INTEGER NOT NULL DEFAULT 0",
+    "ALTER TABLE traces ADD COLUMN IF NOT EXISTS unavailable_model_call_count INTEGER NOT NULL DEFAULT 0",
+    "ALTER TABLE usage_events ADD COLUMN IF NOT EXISTS cost_status TEXT NOT NULL DEFAULT 'complete'",
+    "ALTER TABLE usage_events ADD COLUMN IF NOT EXISTS priced_model_call_count INTEGER NOT NULL DEFAULT 0",
+    "ALTER TABLE usage_events ADD COLUMN IF NOT EXISTS unavailable_model_call_count INTEGER NOT NULL DEFAULT 0",
+    "UPDATE traces SET cost_status = CASE WHEN model_call_count = 0 THEN 'empty' ELSE 'complete' END, "
+    "priced_model_call_count = model_call_count, unavailable_model_call_count = 0",
+    "UPDATE usage_events SET cost_status = CASE WHEN model_call_count = 0 THEN 'empty' ELSE 'complete' END, "
+    "priced_model_call_count = model_call_count, unavailable_model_call_count = 0",
+)
+
+MIGRATIONS: tuple[Migration, ...] = (
+    Migration(
+        version=1,
+        name="baseline",
+        sqlite_statements=_BASELINE_SQLITE,
+        postgres_statements=_BASELINE_POSTGRES,
+    ),
+    Migration(
+        version=2,
+        name="idempotent_usage_events",
+        sqlite_statements=_DEDUPE_AND_CONSTRAIN_USAGE_EVENTS,
+        postgres_statements=_DEDUPE_AND_CONSTRAIN_USAGE_EVENTS,
+    ),
+    Migration(
+        version=3,
+        name="pagination_indexes",
+        sqlite_statements=_PAGINATION_INDEXES,
+        postgres_statements=_PAGINATION_INDEXES,
+    ),
+    Migration(
+        version=4,
+        name="cost_completeness",
+        sqlite_statements=_COST_COMPLETENESS_SQLITE,
+        postgres_statements=_COST_COMPLETENESS_POSTGRES,
+    ),
+    Migration(
+        version=5,
+        name="intervention_ledger",
+        sqlite_statements=(
+            "CREATE TABLE IF NOT EXISTS interventions ("
+            "project_id TEXT NOT NULL REFERENCES projects(project_id), "
+            "intervention_id TEXT NOT NULL, baseline_run_id TEXT NOT NULL REFERENCES traces(run_id), "
+            "candidate_run_id TEXT NOT NULL REFERENCES traces(run_id), payload_json TEXT NOT NULL, "
+            "PRIMARY KEY(project_id, intervention_id))",
+        ),
+        postgres_statements=(
+            "CREATE TABLE IF NOT EXISTS interventions ("
+            "project_id TEXT NOT NULL REFERENCES projects(project_id), "
+            "intervention_id TEXT NOT NULL, baseline_run_id TEXT NOT NULL REFERENCES traces(run_id), "
+            "candidate_run_id TEXT NOT NULL REFERENCES traces(run_id), payload_json TEXT NOT NULL, "
+            "PRIMARY KEY(project_id, intervention_id))",
+        ),
+    ),
+)
+
+
+def _ensure_migrations_table_sqlite(conn) -> None:
+    conn.execute(
+        """
+        CREATE TABLE IF NOT EXISTS schema_migrations (
+            version INTEGER PRIMARY KEY,
+            name TEXT NOT NULL,
+            applied_at TEXT DEFAULT CURRENT_TIMESTAMP
+        )
+        """
+    )
+
+
+def _ensure_migrations_table_postgres(conn) -> None:
+    conn.execute(
+        "CREATE TABLE IF NOT EXISTS schema_migrations ("
+        "version INTEGER PRIMARY KEY, name TEXT NOT NULL, "
+        "applied_at TIMESTAMPTZ DEFAULT now())"
+    )
+
+
+def apply_sqlite_migrations(conn) -> None:
+    """Apply pending migrations to a SQLite connection inside its open transaction."""
+    import sqlite3
+
+    _ensure_migrations_table_sqlite(conn)
+    applied = {row[0] for row in conn.execute("SELECT version FROM schema_migrations").fetchall()}
+    for migration in MIGRATIONS:
+        if migration.version in applied:
+            continue
+        try:
+            for statement in migration.sqlite_statements:
+                try:
+                    conn.execute(statement)
+                except sqlite3.OperationalError as exc:
+                    # SQLite has no `ADD COLUMN IF NOT EXISTS`. Concurrent
+                    # initializers can both observe migration 4 as pending;
+                    # after one commits the column, the other receives this
+                    # narrow duplicate-column error. Treat only that verified
+                    # race as idempotent and preserve every other SQL failure.
+                    if not (
+                        statement.lstrip().upper().startswith("ALTER TABLE")
+                        and "duplicate column name" in str(exc).lower()
+                    ):
+                        raise
+            conn.execute(
+                "INSERT OR IGNORE INTO schema_migrations(version, name) VALUES (?, ?)",
+                (migration.version, migration.name),
+            )
+        except sqlite3.Error as exc:
+            raise MigrationError(
+                f"migration {migration.version} ({migration.name}) failed: {exc}. "
+                "The transaction was rolled back; the store is unchanged. Fix the "
+                "underlying issue (e.g. free disk space, resolve a lock) and retry."
+            ) from exc
+
+
+def apply_postgres_migrations(conn) -> None:
+    """Apply pending migrations to a psycopg connection inside its open transaction."""
+    import psycopg
+
+    _ensure_migrations_table_postgres(conn)
+    applied = {row[0] for row in conn.execute("SELECT version FROM schema_migrations").fetchall()}
+    for migration in MIGRATIONS:
+        if migration.version in applied:
+            continue
+        try:
+            for statement in migration.postgres_statements:
+                conn.execute(statement)
+            conn.execute(
+                "INSERT INTO schema_migrations(version, name) VALUES (%s, %s) "
+                "ON CONFLICT (version) DO NOTHING",
+                (migration.version, migration.name),
+            )
+        except psycopg.Error as exc:
+            raise MigrationError(
+                f"migration {migration.version} ({migration.name}) failed: {exc}. "
+                "The transaction was rolled back; the store is unchanged. Fix the "
+                "underlying issue (e.g. permissions, a blocking lock) and retry."
+            ) from exc