@@ -0,0 +1,187 @@
+# SPDX-FileCopyrightText: Sudo Apt Holdings LLC
+# SPDX-License-Identifier: Apache-2.0
+defmodule Trinity.Telemetry.Costs do
+  @moduledoc """
+  What the model calls have cost, and whether a budget has been passed (slice 090).
+
+  **This is a read, not a pipeline.** Slice 011 already writes a `usage_events` row per completed
+  call with the cost computed from the model registry's price. Nothing here recomputes that, and
+  nothing here is a telemetry handler: a handler that failed or was detached would silently stop
+  the ledger, and a missing bill is worse than a missing chart. The events in
+  `docs/telemetry.md` describe the same calls, and the dashboards read them, but the money is read
+  from the rows.
+
+  ## Budgets
+
+  Configured rather than stored, because there is no settings table and inventing one for three
+  numbers would be the larger change:
+
+      config :trinity, :budgets, day: 5.0, session: 1.0, persona: 20.0
+
+  A budget that is not configured is not enforced. `check/2` answers `:ok` or
+  `{:over, spent, limit}` and emits `[:trinity, :budget, :exceeded]` when it is over, so the
+  warning reaches a dashboard whether or not anything is blocking on it.
+
+  **Blocking is separate from warning, and off by default.** `config :trinity, :budgets,
+  block_when_over: true` makes the session refuse a new turn. It is off because a budget that
+  silently stops an agent mid-task is a failure a person cannot diagnose from the outside, and the
+  warning is what makes the number visible before it becomes a wall.
+  """
+
+  import Ecto.Query
+
+  alias Trinity.Repo
+
+  # The table, not the schema. `Trinity.LLM` is a sub-boundary that depends on `Trinity`, so a
+  # module in `Trinity` naming `Trinity.LLM.Usage` would be a cycle and the compiler refuses it.
+  # That refusal is right rather than inconvenient: this module reads a ledger, it does not use the
+  # LLM's API, and every query here is an aggregate that needs no struct. The column names are the
+  # contract, and the test asserts they still exist.
+  @table "usage_events"
+
+  @scopes [:day, :session, :persona]
+
+  @doc "The scopes a budget can be set for."
+  @spec scopes() :: [atom()]
+  def scopes, do: @scopes
+
+  @doc "Total cost in US dollars across every recorded call, optionally since a time."
+  @spec total(keyword()) :: float()
+  def total(opts \\ []) do
+    @table
+    |> since(opts[:since])
+    |> select([u], sum(u.cost_usd))
+    |> Repo.one()
+    |> zero_if_nil()
+  end
+
+  @doc "Total cost for one session."
+  @spec for_session(String.t()) :: float()
+  def for_session(session_id) do
+    @table
+    |> where([u], u.session_id == ^session_id)
+    |> select([u], sum(u.cost_usd))
+    |> Repo.one()
+    |> zero_if_nil()
+  end
+
+  @doc """
+  Total cost for one persona, summed across its sessions.
+
+  `usage_events` carries the session, not the persona, so this joins. Storing the persona on the
+  usage row would make this a simpler query and a wrong one: a session's persona can change, and
+  the cost belongs to the session that incurred it.
+  """
+  @spec for_persona(String.t()) :: float()
+  def for_persona(persona_id) do
+    from(u in @table,
+      join: s in "sessions",
+      on: s.id == u.session_id,
+      where: s.persona_id == ^persona_id,
+      select: sum(u.cost_usd)
+    )
+    |> Repo.one()
+    |> zero_if_nil()
+  end
+
+  @doc "Total cost today, in UTC."
+  @spec for_today() :: float()
+  def for_today, do: total(since: DateTime.utc_now() |> DateTime.to_date() |> start_of_day())
+
+  @doc "Totals by day, newest first, as `{date, cost}`."
+  @spec by_day(pos_integer()) :: [{Date.t(), float()}]
+  def by_day(days \\ 30) do
+    since = Date.utc_today() |> Date.add(-days) |> start_of_day()
+
+    @table
+    |> where([u], u.inserted_at >= ^since)
+    |> group_by([u], fragment("date(?)", u.inserted_at))
+    |> select([u], {fragment("date(?)", u.inserted_at), sum(u.cost_usd)})
+    |> Repo.all()
+    |> Enum.map(fn {d, c} -> {to_date(d), zero_if_nil(c)} end)
+    |> Enum.sort({:desc, Date})
+  end
+
+  @doc "Totals by model, largest first, as `{model_id, cost, calls}`."
+  @spec by_model(keyword()) :: [{String.t(), float(), non_neg_integer()}]
+  def by_model(opts \\ []) do
+    @table
+    |> since(opts[:since])
+    |> group_by([u], u.model_id)
+    |> select([u], {u.model_id, sum(u.cost_usd), count(u.id)})
+    |> Repo.all()
+    |> Enum.map(fn {m, c, n} -> {m, zero_if_nil(c), n} end)
+    |> Enum.sort_by(&elem(&1, 1), :desc)
+  end
+
+  @doc "The configured budget for a scope, or `nil` when none is set."
+  @spec budget(atom()) :: float() | nil
+  def budget(scope) when scope in @scopes do
+    case Application.get_env(:trinity, :budgets, [])[scope] do
+      n when is_number(n) -> n / 1
+      _ -> nil
+    end
+  end
+
+  @doc "Whether a new turn should be refused when a budget is passed. Off unless configured."
+  @spec blocking?() :: boolean()
+  def blocking?, do: Application.get_env(:trinity, :budgets, [])[:block_when_over] == true
+
+  @doc """
+  Whether a scope is over its budget, emitting the warning event when it is.
+
+  `:ok` when no budget is set for the scope, because an unconfigured budget is not a budget of
+  zero. That distinction matters: the alternative silently blocks every call on a fresh install.
+  """
+  @spec check(atom(), String.t() | nil) :: :ok | {:over, float(), float()}
+  def check(scope, scope_id \\ nil)
+
+  def check(scope, scope_id) when scope in @scopes do
+    case budget(scope) do
+      nil ->
+        :ok
+
+      limit ->
+        spent = spent(scope, scope_id)
+
+        if spent > limit do
+          Trinity.Telemetry.budget_exceeded(scope, scope_id, spent, limit)
+          {:over, spent, limit}
+        else
+          :ok
+        end
+    end
+  end
+
+  def check(_scope, _scope_id), do: :ok
+
+  @doc "Every configured scope that is over, for a caller that wants the whole picture at once."
+  @spec over(String.t() | nil, String.t() | nil) :: [{atom(), float(), float()}]
+  def over(session_id \\ nil, persona_id \\ nil) do
+    [{:day, nil}, {:session, session_id}, {:persona, persona_id}]
+    |> Enum.filter(fn {scope, id} -> scope == :day or id != nil end)
+    |> Enum.flat_map(fn {scope, id} ->
+      case check(scope, id) do
+        {:over, spent, limit} -> [{scope, spent, limit}]
+        :ok -> []
+      end
+    end)
+  end
+
+  defp spent(:day, _), do: for_today()
+  defp spent(:session, id) when is_binary(id), do: for_session(id)
+  defp spent(:persona, id) when is_binary(id), do: for_persona(id)
+  defp spent(_, _), do: 0.0
+
+  defp since(query, nil), do: query
+  defp since(query, %DateTime{} = at), do: where(query, [u], u.inserted_at >= ^at)
+
+  defp start_of_day(%Date{} = d), do: DateTime.new!(d, ~T[00:00:00], "Etc/UTC")
+
+  defp to_date(%Date{} = d), do: d
+  defp to_date(s) when is_binary(s), do: Date.from_iso8601!(s)
+
+  defp zero_if_nil(nil), do: 0.0
+  defp zero_if_nil(%Decimal{} = d), do: Decimal.to_float(d)
+  defp zero_if_nil(n) when is_number(n), do: n / 1
+end
@@ -0,0 +1,182 @@
+# SPDX-FileCopyrightText: Sudo Apt Holdings LLC
+# SPDX-License-Identifier: Apache-2.0
+defmodule Trinity.Telemetry.CostsTest do
+  @moduledoc """
+  Slice 090, AC2 (the totals half, retagged `[auto]`): the ledger's totals equal the sum of the
+  rows, and a budget that is passed emits its warning.
+
+  The SLICE made this criterion manual, to be checked by eye against a seeded dataset. A total is
+  arithmetic, and arithmetic is the last thing that should be checked by looking at it, so the
+  totals are asserted here and the manual queue keeps only the part that needs a person: the
+  blocking behaviour and its message on screen.
+  """
+  use Trinity.DataCase, async: false
+
+  alias Trinity.Repo
+  alias Trinity.Sessions
+  alias Trinity.Telemetry.Costs
+
+  defp seed!(session_id, cost, opts \\ []) do
+    Repo.insert_all("usage_events", [
+      %{
+        id: Trinity.UUID.generate(),
+        model_id: Keyword.get(opts, :model, "fake:chat"),
+        provider: "fake",
+        kind: "stream",
+        input_tokens: 10,
+        output_tokens: 20,
+        cached_tokens: 0,
+        reasoning_tokens: 0,
+        cost_usd: cost,
+        session_id: session_id,
+        # Encoded here rather than passed as a map: a schemaless insert has no schema to tell the
+        # adapter this column is JSON, and SQLite refuses a bare map.
+        provider_meta: JSON.encode!(%{}),
+        inserted_at: Keyword.get(opts, :at, DateTime.utc_now() |> DateTime.truncate(:second))
+      }
+    ])
+  end
+
+  defp session!(opts \\ []) do
+    {:ok, s} =
+      Sessions.create_session(
+        Enum.into(opts, %{persona_id: Sessions.default_persona().id, title: "t"})
+      )
+
+    s
+  end
+
+  setup do
+    prior = Application.get_env(:trinity, :budgets)
+
+    on_exit(fn ->
+      if prior,
+        do: Application.put_env(:trinity, :budgets, prior),
+        else: Application.delete_env(:trinity, :budgets)
+    end)
+
+    :ok
+  end
+
+  describe "totals equal the sum of the rows" do
+    test "across everything, and per session" do
+      a = session!()
+      b = session!()
+
+      seed!(a.id, 1.50)
+      seed!(a.id, 0.25)
+      seed!(b.id, 2.00)
+
+      assert_in_delta Costs.total(), 3.75, 0.0001
+      assert_in_delta Costs.for_session(a.id), 1.75, 0.0001
+      assert_in_delta Costs.for_session(b.id), 2.00, 0.0001
+    end
+
+    test "per persona, summed across that persona's sessions" do
+      {:ok, persona} = Trinity.Personas.create(%{name: "auditor", soul: "careful"})
+      mine = session!(persona_id: persona.id)
+      theirs = session!()
+
+      seed!(mine.id, 3.00)
+      seed!(theirs.id, 9.99)
+
+      assert_in_delta Costs.for_persona(persona.id), 3.00, 0.0001
+    end
+
+    test "by model, largest first, with the call count" do
+      s = session!()
+      seed!(s.id, 0.10, model: "cheap")
+      seed!(s.id, 0.10, model: "cheap")
+      seed!(s.id, 5.00, model: "dear")
+
+      assert [{"dear", dear, 1}, {"cheap", cheap, 2}] = Costs.by_model()
+      assert_in_delta dear, 5.00, 0.0001
+      assert_in_delta cheap, 0.20, 0.0001
+    end
+
+    test "an empty ledger is zero, not nil" do
+      # sum() over no rows is NULL, and a nil reaching a template renders as nothing rather than
+      # as a number, which reads as "no data" when it means "no spend".
+      assert Costs.total() == 0.0
+      assert Costs.for_session(session!().id) == 0.0
+      assert Costs.by_day() == []
+    end
+  end
+
+  describe "budgets" do
+    test "an unconfigured budget is not a budget of zero" do
+      Application.delete_env(:trinity, :budgets)
+      s = session!()
+      seed!(s.id, 1_000.0)
+
+      # The alternative silently blocks every call on a fresh install.
+      assert Costs.budget(:day) == nil
+      assert Costs.check(:day) == :ok
+      assert Costs.check(:session, s.id) == :ok
+    end
+
+    test "passing a budget answers with what was spent and what the limit was" do
+      Application.put_env(:trinity, :budgets, session: 1.0)
+      s = session!()
+      seed!(s.id, 2.50)
+
+      assert {:over, spent, limit} = Costs.check(:session, s.id)
+      assert_in_delta spent, 2.50, 0.0001
+      assert limit == 1.0
+    end
+
+    test "passing a budget emits the warning event, whether or not anything blocks on it" do
+      Application.put_env(:trinity, :budgets, day: 0.5)
+      s = session!()
+      seed!(s.id, 0.75)
+
+      ref = make_ref()
+      me = self()
+      handler = "budget-#{System.unique_integer([:positive])}"
+
+      :telemetry.attach(
+        handler,
+        [:trinity, :budget, :exceeded],
+        fn _, m, md, _ ->
+          send(me, {ref, m, md})
+        end,
+        nil
+      )
+
+      on_exit(fn -> :telemetry.detach(handler) end)
+
+      assert {:over, _, _} = Costs.check(:day)
+      assert_receive {^ref, %{spent_usd: _, limit_usd: 0.5}, %{scope: :day}}
+    end
+
+    test "blocking is off unless configured, and separate from warning" do
+      Application.put_env(:trinity, :budgets, day: 0.01)
+      refute Costs.blocking?()
+
+      Application.put_env(:trinity, :budgets, day: 0.01, block_when_over: true)
+      assert Costs.blocking?()
+    end
+
+    test "over/2 reports every configured scope that is past its limit" do
+      {:ok, persona} = Trinity.Personas.create(%{name: "spender", soul: "eager"})
+      s = session!(persona_id: persona.id)
+      seed!(s.id, 4.00)
+
+      Application.put_env(:trinity, :budgets, day: 1.0, session: 10.0, persona: 2.0)
+
+      scopes = Costs.over(s.id, persona.id) |> Enum.map(&elem(&1, 0)) |> Enum.sort()
+      assert scopes == [:day, :persona]
+    end
+  end
+
+  test "the columns this module reads still exist" do
+    # The queries are schemaless, so the column names are the contract with slice 011's schema and
+    # nothing else checks them. A rename there should fail here rather than in a dashboard.
+    {:ok, %{columns: columns}} =
+      Repo.query("SELECT * FROM usage_events LIMIT 0")
+
+    for column <- ~w(cost_usd session_id model_id inserted_at id) do
+      assert column in columns, "usage_events lost the #{column} column this ledger reads"
+    end
+  end
+end