activity timestamp, no typed/spoken split, and no priced cost. The struct is

the contract: a field added there is published to the internet.

Totals are derived only from the two planes that already hold a merged total,

`turn_receipts.usage` and `voice_sessions.usage`. Provider steps, voice

response receipts, tool-step invocation counts, and off-path shadow-program

runs are excluded, so no account is credited twice and none is credited for

work it did not drive. Accounts appear only while active, not withheld by

Totals are derived only from the three planes that already hold a merged

total: `turn_receipts.usage`, `voice_sessions.usage`, and — for thread-fenced

grants only — `inference_grants.usage`, joined to the account through the

thread's owner visitor. Provider steps, voice response receipts, tool-step

invocation counts, off-path shadow-program runs, and conversation-fenced

grants (whose chat-lane spend the turn-receipt plane already claims) are

excluded, so no account is credited twice and none is credited for work it did

not drive. Accounts appear only while active, not withheld by

`users.public_leaderboard_opted_out`, and above zero tokens; banned accounts

and legacy browser-only visitors never appear. Deleting product data under

DATA-004 removes an account from the board by cascade, without a separate

          Repo.rollback(:grant_not_active)

      end

    end)

    |> case do

      {:ok, %Grant{thread_id: thread_id} = updated} ->

        # A thread grant's usage is a leaderboard plane (LEADERBOARD-001), so

        # this is the one place a thread's token total can change. Conversation

        # grants are not counted there and stay silent.

        if is_binary(thread_id), do: :ok = OpenAgents.Leaderboard.invalidate()

        {:ok, updated}

      {:error, _reason} = error ->

        error

    end

  end

  @doc "Revoke a grant. Idempotent for already-terminal grants."

  The public token leaderboard.

  PostgreSQL is authoritative (`INVARIANTS.md` DATA-001). This module reads the

  two tables that hold per-account token truth and publishes the bounded

  three tables that hold per-account token truth and publishes the bounded

  projection described by LEADERBOARD-001 — nothing else crosses the account

  boundary.

  shadow-program runs are off-path under PROGRAM-002 and earn no credit. See

  `docs/LEADERBOARD.md`.

  `inference_grants.usage` counts only for thread-fenced grants. A grant names

  exactly one fence — a thread or a conversation, never both (THREAD-001) — and

  its usage map is the forward-only merge of every metered call it authorized,

  so a thread grant is the one place a coder session's spend lands. A

  conversation-fenced grant backs work inside the chat lane the turn-receipt

  arm already claims, so counting it here would credit the same account twice.

  ## Fan-out

  The board is public, so viewers are unbounded and anonymous. Reads never touch

  alias OpenAgents.Conversations.Turn

  alias OpenAgents.Conversations.TurnReceipt

  alias OpenAgents.Conversations.Visitor

  alias OpenAgents.Inference.Grant

  alias OpenAgents.Leaderboard.Entry

  alias OpenAgents.Leaderboard.Server

  alias OpenAgents.Repo

  alias OpenAgents.Threads.Thread

  alias OpenAgents.Voice.Session

  @topic "leaderboard"

  end

  defp account_totals do

    from(row in subquery(union_all(typed_turn_usage(), ^voice_session_usage())),

    usage_union =

      typed_turn_usage()

      |> union_all(^voice_session_usage())

      |> union_all(^thread_grant_usage())

    from(row in subquery(usage_union),

      group_by: row.user_id,

      select: %{user_id: row.user_id, tokens: fragment("SUM(?)::bigint", row.tokens)}

    )

      }

    )

  end

  # Coder and thread spend. Only thread-fenced grants count: a grant's fence is

  # exactly one of thread or conversation (THREAD-001), and conversation-fenced

  # grants back the chat lane whose merged total the turn-receipt arm above

  # already claims. The inner join on the thread is what enforces the fence —

  # a grant with a NULL thread_id matches no thread row.

  defp thread_grant_usage do

    from(grant in Grant,

      join: thread in Thread,

      on: thread.id == grant.thread_id,

      join: visitor in Visitor,

      on: visitor.id == thread.owner_visitor_id,

      where: not is_nil(visitor.user_id),

      select: %{

        user_id: visitor.user_id,

        tokens:

          fragment(

            """

            GREATEST(

              CASE WHEN ? ->> 'total_tokens' ~ '^[0-9]+$' THEN (? ->> 'total_tokens')::bigint ELSE 0 END,

              CASE WHEN ? ->> 'input_tokens' ~ '^[0-9]+$' THEN (? ->> 'input_tokens')::bigint ELSE 0 END

                + CASE WHEN ? ->> 'output_tokens' ~ '^[0-9]+$' THEN (? ->> 'output_tokens')::bigint ELSE 0 END

            )

            """,

            grant.usage,

            grant.usage,

            grant.usage,

            grant.usage,

            grant.usage,

            grant.usage

          )

      }

    )

  end

end

  alias OpenAgents.Context.Composer

  alias OpenAgents.Conversations

  alias OpenAgents.DataRights

  alias OpenAgents.Inference

  alias OpenAgents.Leaderboard

  alias OpenAgents.Providers.Request

  alias OpenAgents.Threads

  alias OpenAgents.Voice

  alias OpenAgents.Voice.Config

  alias OpenAgents.Voice.ProviderEvent

    assert entry.total_tokens == 12

  end

  test "counts a thread grant's spend for its owning account" do

    # A coder session runs on a thread, and its spend lands on the grant's

    # forward-only usage map rather than on any turn receipt. The board sums it

    # alongside the chat planes.

    mixed = account("thread-mixed")

    coder = account("thread-only")

    complete_typed_turn(mixed, "Typed alongside the coder.", %{

      "input_tokens" => 100,

      "output_tokens" => 40,

      "total_tokens" => 140

    })

    record_thread_grant_usage(mixed, %{

      "input_tokens" => 45,

      "output_tokens" => 15,

      "total_tokens" => 60

    })

    record_thread_grant_usage(coder, %{

      "input_tokens" => 3,

      "output_tokens" => 2,

      "total_tokens" => 5

    })

    assert [first, second] = Leaderboard.compute_entries()

    assert first.rank == 1

    assert first.github_login == mixed.github_login

    assert first.total_tokens == 200

    assert second.rank == 2

    assert second.github_login == coder.github_login

    assert second.total_tokens == 5

  end

  test "does not count a conversation-fenced grant's usage" do

    # A conversation grant backs the chat lane the turn-receipt arm already

    # claims (THREAD-001 gives a grant exactly one fence). Counting the grant

    # too would credit the same account twice.

    user = account("conversation-grant")

    complete_typed_turn(user, "The receipt claims this lane.", %{

      "input_tokens" => 7,

      "output_tokens" => 5,

      "total_tokens" => 12

    })

    conversation = conversation_for(user)

    {:ok, grant, _token} =

      Inference.mint(%{

        owner_visitor_id: conversation.visitor_id,

        conversation_id: conversation.id,

        machine_id: nil

      })

    {:ok, _grant} =

      Inference.record_usage(grant, %{

        "input_tokens" => 900,

        "output_tokens" => 99,

        "total_tokens" => 999

      })

    assert [entry] = Leaderboard.compute_entries()

    assert entry.total_tokens == 12

  end

  test "omits an account whose only thread grant has spent nothing" do

    # A freshly minted grant carries an empty usage map. Authority is not

    # activity, so the mint alone publishes nothing.

    user = account("thread-idle")

    {:ok, thread} = Threads.open(user, "Minted and never spent")

    {:ok, _thread, _grant, _token} = Threads.mint_grant(thread)

    assert Leaderboard.compute_entries() == []

  end

  test "omits accounts with no tokens" do

    silent = account("silent")

    {:ok, _conversation} = Conversations.ensure_conversation(silent)

    inference

  end

  defp record_thread_grant_usage(user, usage) do

    {:ok, thread} = Threads.open(user, "Coder session")

    {:ok, _thread, grant, _token} = Threads.mint_grant(thread)

    {:ok, _grant} = Inference.record_usage(grant, usage)

    :ok

  end

  defp record_voice_usage(user, rtc_id, usage) do

    conversation = conversation_for(user)

    {:ok, session} = Voice.admit_session(conversation, voice_config())