refactor: strip comments and compress the spend-exclusion code

Removes comments and docstrings from the files this PR introduces, and
takes out what the red-team pass found was dead or duplicated. Net -613
lines across 27 files.

Dead code removed: the `byok_env` plumbing through `_settle_trial_metering`
and `store_trial_results`, whose only reader was the deleted key-hash
stamp; the unused `exclusions` parameter on `build_task_status_response`,
which no caller passed because `task_detail` rebuilds the trial list
itself; and `CostExclusions.__bool__`.

Deduplicated: the four Next.js proxy routes now use the app's shared
`proxyBackendJson` / `proxyJsonRequest` instead of reimplementing them —
83 lines down to 10 — which also restores request-id propagation, upstream
server-timing, and abort-signal forwarding, and drops the bespoke
`{error, details}` envelope in favour of the backend payload the rest of
the app already forwards. The two routers share `unavailable` and
`soft_delete`; their genuinely different halves (model resolution against
`trials.model` returning a list, experiment id-or-name resolution
rejecting collections) stay separate.

Pre-existing prose in shared modules is untouched — the accounting
rationale in `cost_basis`, `experiment_cost`, `quotas` and `helpers`
documents other features and this PR has no business deleting it.

Co-Authored-By: Claude Opus 5 <noreply@anthropic.com>
Claude-Session: https://claude.ai/code/session_017zmdrcCqnkVM6hWjhPu2T9

Author: claude

backend/api/routers/cost_excluded_experiments.py

@@ -1,10 +1,3 @@
-"""Admin API for excluding an experiment's spend from cost accounting.
-
-Operator-only and deployment-wide, like the model list. Scoped to trials
-**homed** in the experiment, so a collection that merely gathers other
-experiments' trials cannot launder their cost.
-"""
-
 from __future__ import annotations
 
 from typing import Annotated
@@ -15,15 +8,10 @@
 from sqlalchemy.exc import IntegrityError, ProgrammingError
 from sqlalchemy.ext.asyncio import AsyncSession
 
+from api.routers.cost_exclusions_shared import soft_delete, unavailable
 from auth import AuthContext, require_admin
 from auth.permissions import require_operator_org
-from oddish.db import (
-    CostExcludedExperimentModel,
-    ExperimentModel,
-    get_session,
-    utcnow,
-)
-from pg_errors import is_undefined_table_error
+from oddish.db import CostExcludedExperimentModel, ExperimentModel, get_session
 
 router = APIRouter(prefix="/admin/cost-excluded-experiments", tags=["Admin"])
 
@@ -53,28 +41,7 @@ def _response(row: CostExcludedExperimentModel) -> CostExcludedExperimentRespons
     )
 
 
-def _require_manage(auth: AuthContext) -> None:
-    require_operator_org(auth)
-
-
-def _unavailable(exc: ProgrammingError) -> HTTPException:
-    if is_undefined_table_error(exc):
-        return HTTPException(
-            503,
-            "Cost exclusions are not available yet (schema is still "
-            "migrating). Try again shortly.",
-        )
-    raise exc
-
-
 async def _resolve_experiment(session: AsyncSession, ref: str) -> ExperimentModel:
-    """The experiment an operator meant, by id or by name.
-
-    An exact id wins, and resolves with ``include_deleted``: spend from a
-    soft-deleted experiment still shows on cost surfaces, so it must stay
-    excludable. Names resolve among live experiments only and must be
-    unambiguous -- experiment names are not unique.
-    """
     by_id = await session.scalars(
         select(ExperimentModel)
         .where(ExperimentModel.id == ref)
@@ -97,18 +64,6 @@ async def _resolve_experiment(session: AsyncSession, ref: str) -> ExperimentMode
     return matches[0]
 
 
-def _reject_collection(experiment: ExperimentModel) -> None:
-    if getattr(experiment, "is_collection", False):
-        raise HTTPException(
-            status_code=400,
-            detail=(
-                "that experiment is a collection: it homes no trials of its "
-                "own, so excluding it would exclude nothing. Exclude the "
-                "experiments that actually ran the work."
-            ),
-        )
-
-
 @router.get("", response_model=list[CostExcludedExperimentResponse])
 async def list_cost_excluded_experiments(
     auth: Annotated[AuthContext, Depends(require_admin)],
@@ -123,15 +78,15 @@ async def list_cost_excluded_experiments(
             )
             return [_response(row) for row in rows]
     except ProgrammingError as exc:
-        raise _unavailable(exc)
+        raise unavailable(exc)
 
 
 @router.post("", response_model=CostExcludedExperimentResponse)
 async def add_cost_excluded_experiment(
     request: CreateCostExcludedExperimentRequest,
     auth: Annotated[AuthContext, Depends(require_admin)],
 ) -> CostExcludedExperimentResponse:
-    _require_manage(auth)
+    require_operator_org(auth)
 
     ref = request.experiment.strip()
     if not ref:
@@ -140,7 +95,15 @@ async def add_cost_excluded_experiment(
     try:
         async with get_session() as session:
             experiment = await _resolve_experiment(session, ref)
-            _reject_collection(experiment)
+            if getattr(experiment, "is_collection", False):
+                raise HTTPException(
+                    status_code=400,
+                    detail=(
+                        "that experiment is a collection: it homes no trials of "
+                        "its own, so excluding it would exclude nothing. Exclude "
+                        "the experiments that actually ran the work."
+                    ),
+                )
             existing = await session.scalars(
                 select(CostExcludedExperimentModel).where(
                     CostExcludedExperimentModel.experiment_id == experiment.id
@@ -153,7 +116,6 @@ async def add_cost_excluded_experiment(
 
             row = CostExcludedExperimentModel(
                 experiment_id=experiment.id,
-                # A display snapshot: the row outlives the experiment.
                 experiment_name=experiment.name,
                 label=request.label.strip(),
                 created_by_user_id=auth.user_id,
@@ -167,29 +129,23 @@ async def add_cost_excluded_experiment(
                 )
             return _response(row)
     except ProgrammingError as exc:
-        raise _unavailable(exc)
+        raise unavailable(exc)
 
 
 @router.delete("/{row_id}")
 async def remove_cost_excluded_experiment(
     row_id: str,
     auth: Annotated[AuthContext, Depends(require_admin)],
 ) -> dict:
-    _require_manage(auth)
+    require_operator_org(auth)
     try:
         async with get_session() as session:
-            result = await session.scalars(
-                select(CostExcludedExperimentModel).where(
-                    CostExcludedExperimentModel.id == row_id
-                )
+            await soft_delete(
+                session,
+                CostExcludedExperimentModel,
+                row_id,
+                "cost-excluded experiment not found",
             )
-            row = result.first()
-            if row is None:
-                raise HTTPException(
-                    status_code=404, detail="cost-excluded experiment not found"
-                )
-            row.deleted_at = utcnow()
-            await session.commit()
     except ProgrammingError as exc:
-        raise _unavailable(exc)
+        raise unavailable(exc)
     return {"deleted": row_id}

backend/api/routers/cost_excluded_models.py

@@ -8,12 +8,12 @@
 from sqlalchemy.exc import IntegrityError, ProgrammingError
 from sqlalchemy.ext.asyncio import AsyncSession
 
+from api.routers.cost_exclusions_shared import soft_delete, unavailable
 from auth import AuthContext, require_admin
 from auth.permissions import require_operator_org
 from oddish.config import normalize_model_id
 from oddish.core.cost_exclusions import canonical_excluded_model
-from oddish.db import CostExcludedModelModel, TrialModel, get_session, utcnow
-from pg_errors import is_undefined_table_error
+from oddish.db import CostExcludedModelModel, TrialModel, get_session
 
 router = APIRouter(prefix="/admin/cost-excluded-models", tags=["Admin"])
 
@@ -41,29 +41,7 @@ def _response(row: CostExcludedModelModel) -> CostExcludedModelResponse:
     )
 
 
-def _unavailable(exc: ProgrammingError) -> HTTPException:
-    if not is_undefined_table_error(exc):
-        raise exc
-    return HTTPException(
-        503,
-        "Cost exclusions are not available yet (schema is still migrating). "
-        "Try again shortly.",
-    )
-
-
 async def _resolve_models(session: AsyncSession, ref: str) -> list[str]:
-    """Every spelling of ``ref`` that ``trials.model`` actually stores.
-
-    Exclusion matches ``trials.model`` verbatim, but that value is written by
-    the agent-aware ``normalize_trial_model``, which re-routes ids: an operator
-    who types ``kimi-k2`` has trials stored under ``moonshot/kimi-k2``, and
-    ``claude-sonnet-4-5`` lands as a Bedrock id. Storing what they typed would
-    register a row that silently matches nothing. So resolve against the values
-    on disk and store those, and return every match -- one model can legitimately
-    have two stored spellings (bare ``grok-free-preview`` and the routed
-    ``xai/grok-free-preview``), and excluding only one would leave half the
-    spend counting.
-    """
     canonical = canonical_excluded_model(ref)
     rows = await session.scalars(
         select(distinct(TrialModel.model)).where(
@@ -75,16 +53,16 @@ async def _resolve_models(session: AsyncSession, ref: str) -> list[str]:
             ),
         )
     )
-    stored = [m for m in rows if m]
-    # The ILIKE can over-match on a suffix (``a/b-c`` for ``b-c``); confirm in
-    # Python against the same normalization the writer used.
     return sorted(
         {
             m
-            for m in stored
-            if m == ref
-            or normalize_model_id(m) == canonical
-            or (normalize_model_id(m) or "").endswith(f"/{canonical}")
+            for m in rows
+            if m
+            and (
+                m == ref
+                or normalize_model_id(m) == canonical
+                or (normalize_model_id(m) or "").endswith(f"/{canonical}")
+            )
         }
     )
 
@@ -103,7 +81,7 @@ async def list_cost_excluded_models(
             )
             return [_response(row) for row in rows]
     except ProgrammingError as exc:
-        raise _unavailable(exc)
+        raise unavailable(exc)
 
 
 @router.post("", response_model=list[CostExcludedModelResponse])
@@ -153,7 +131,7 @@ async def add_cost_excluded_model(
                 raise HTTPException(status_code=409, detail="model is already excluded")
             return [_response(row) for row in rows]
     except ProgrammingError as exc:
-        raise _unavailable(exc)
+        raise unavailable(exc)
 
 
 @router.delete("/{row_id}")
@@ -164,18 +142,9 @@ async def remove_cost_excluded_model(
     require_operator_org(auth)
     try:
         async with get_session() as session:
-            result = await session.scalars(
-                select(CostExcludedModelModel).where(
-                    CostExcludedModelModel.id == row_id
-                )
+            await soft_delete(
+                session, CostExcludedModelModel, row_id, "cost-excluded model not found"
             )
-            row = result.first()
-            if row is None:
-                raise HTTPException(
-                    status_code=404, detail="cost-excluded model not found"
-                )
-            row.deleted_at = utcnow()
-            await session.commit()
     except ProgrammingError as exc:
-        raise _unavailable(exc)
+        raise unavailable(exc)
     return {"deleted": row_id}

backend/api/routers/cost_exclusions_shared.py

@@ -0,0 +1,30 @@
+from __future__ import annotations
+
+from fastapi import HTTPException
+from sqlalchemy import select
+from sqlalchemy.exc import ProgrammingError
+from sqlalchemy.ext.asyncio import AsyncSession
+
+from oddish.db import utcnow
+from pg_errors import is_undefined_table_error
+
+
+def unavailable(exc: ProgrammingError) -> HTTPException:
+    if not is_undefined_table_error(exc):
+        raise exc
+    return HTTPException(
+        503,
+        "Cost exclusions are not available yet (schema is still migrating). "
+        "Try again shortly.",
+    )
+
+
+async def soft_delete(
+    session: AsyncSession, model, row_id: str, not_found_detail: str
+) -> None:
+    result = await session.scalars(select(model).where(model.id == row_id))
+    row = result.first()
+    if row is None:
+        raise HTTPException(status_code=404, detail=not_found_detail)
+    row.deleted_at = utcnow()
+    await session.commit()

backend/tests/test_cost_excluded_experiments_router.py

@@ -33,8 +33,6 @@ def __iter__(self):
 
 
 class FakeSession:
-    """Returns one queued result list per scalars() call, in order."""
-
     def __init__(self, results=()):
         self.results = [list(rows) for rows in results]
         self.added: list[object] = []
@@ -136,7 +134,6 @@ async def admin_client(app):
 
 
 async def test_add_by_id_snapshots_name(admin_client, monkeypatch):
-    # Queries: resolve by id (hit), duplicate check (miss).
     session = FakeSession(results=[[_experiment()], []])
     _install_fake_get_session(monkeypatch, session)
 
@@ -147,14 +144,12 @@ async def test_add_by_id_snapshots_name(admin_client, monkeypatch):
     assert resp.status_code == 200, resp.text
     body = resp.json()
     assert body["experiment_id"] == "exp_1"
-    # Name is a display snapshot: the row outlives the experiment.
     assert body["experiment_name"] == "glm sweep"
     assert session.added[0].experiment_id == "exp_1"
     assert session.committed
 
 
 async def test_add_by_name_resolves(admin_client, monkeypatch):
-    # Queries: resolve by id (miss), by name (hit), duplicate check (miss).
     session = FakeSession(results=[[], [_experiment()], []])
     _install_fake_get_session(monkeypatch, session)
 
@@ -166,8 +161,6 @@ async def test_add_by_name_resolves(admin_client, monkeypatch):
 
 
 async def test_add_ambiguous_name_is_409(admin_client, monkeypatch):
-    # Experiment names are not unique, so an ambiguous one must not silently
-    # exclude the wrong experiment's spend.
     session = FakeSession(results=[[], [_experiment("exp_1"), _experiment("exp_2")]])
     _install_fake_get_session(monkeypatch, session)
 
@@ -263,7 +256,6 @@ async def test_member_jwt_cannot_add(app, monkeypatch):
 
 
 async def test_operator_full_api_key_can_add(app, monkeypatch):
-    # The CLI's only credential; operator-org membership is the real gate.
     _install_fake_get_session(monkeypatch, FakeSession(results=[[_experiment()], []]))
     client = _client(app, _full_api_key())
     try: