---
path: /studio/isis/budget-management
surface: studio
domain: isis
auth:
  signed-in + studio entitlement; direct legacy route is Studio-boundary
  hard-blocked unless the localhost E2E lane bypass is present
source: apps/oshun/web/src/app/studio/isis/budget-management/page.tsx
status: walked
last_walked:
  '2026-07-01 real-infra Playwright route journey — Studio-boundary hard-block,
  localhost lane bypass, live `/v1/admin/isis/budget-management` cost-quota
  evaluation, status filtering + local persistence, loading/service-failure /
  malformed/empty-filter/unauthorized/network/anonymous states, route map,
  quick-actions, 44px hit targets, and shared axe gate. Evidence:
  apps/oshun/web/e2e/studio-isis-budget-management.spec.ts and
  WALKTHROUGH/results/v1-real-infra-run-2026-06-22.md#258-2026-07-01-studio-isis-budget-management-coverage'
---

# Isis Budget Management

## Purpose

Read-only admin lane console for per-tenant GPU spend governance. It reads the
real §cost-quota `evaluateBudget` output for each tenant — current utilization,
projected utilization, and the verdict (`ok` / `alert` / `kill-switch-armed` /
`over-cap`) against that tenant's alert and kill-switch fractions — plus a
status rollup. No write verb; a client-side status filter narrows the list.

## Entry points

- Sibling quick-action card from `/studio/isis/cost-tracking`
- Studio index (`/studio`)
- Direct URL / bookmark

## Layout regions

`page.tsx` mounts `ShellLayout active="studio"` and three panels (no breadcrumb
panel).

- **Workspace panel** (`data-isis-budget-management-workspace`):
  - `<h1>` "Isis Budget Management Workspace" (`WorkspaceHeading`)
  - Summary paragraph (`data-isis-budget-management-summary`)
  - Status rollup (`data-budget-summary`) with tenant count and
    `data-budget-status-count={status}` chips
  - Status filter (`data-budget-status-filter` select)
  - Tenant list (`data-budget-tenants`, `<h2>`) of `data-budget-tenant` cards
    carrying `data-budget-tenant-status`
- **Route map panel** (`data-isis-budget-management-route-map`): `<h2>` "Route
  Map" enumerating `STUDIO_ISIS_BUDGET_MANAGEMENT_ROUTE_MAP`
- **Quick-actions panel**: `quickAction` links to
  `/studio/isis/user-feedback-loop` and "Back to Studio workspace index" →
  `/studio`

## States

- [x] **Loading** — `data-budget-loading` "Loading tenant budgets…"
- [x] **Unauthorized** — `data-budget-unauthorized` (admin-scope fail-closed on
      401/403, "Isis workspace scope required to view tenant budgets.")
- [x] **Error** — `data-budget-error` on non-OK / malformed response
- [x] **Ready** — rollup + filter + tenant list render
- [x] **Empty (filtered)** — `data-budget-empty` "No tenant budgets match the
      filter." when the status filter excludes all tenants

## Interactions

### Status filter

- [x] **Status filter** — `data-budget-status-filter` select (`all` / `ok` /
      `alert` / `kill-switch-armed` / `over-cap`); client-side filter, persisted
      via `useStudioWorkspacePersistence` (workspace `isis-budget-management`)

### Route map

- [x] **Route-map articles** — non-interactive path + purpose entries

### Quick-actions

- [x] **Open Isis User Feedback Loop workspace** →
      `/studio/isis/user-feedback-loop`
- [x] **Back to Studio workspace index** → `/studio`

## Data & contracts

- **Reads**: `GET /v1/admin/isis/budget-management` (`BUDGET_ENDPOINT`) on mount
  — tenants + statusCounts + generatedAt
- **Writes**: None (read-only console; filter is client-side)
- **Realtime**: None
- **Caching**: client `fetch` on mount, `cache: 'no-store'`,
  `buildBffAuthHeaders()`; filter preference persisted locally
- **Auth**: admin-scoped fail-closed (401/403 → unauthorized state); route
  behind the signed-in + studio proxy gate; direct legacy URL hard-blocked by
  the Studio Isis boundary unless the localhost E2E lane bypass is present
- **Validation**: strict client-side response guard rejects malformed tenant
  rows, invalid status counts, invalid budget statuses, and invalid persisted
  filter values before rendering
- **Component sources**:
  - `apps/oshun/web/src/components/studio/StudioIsisBudgetManagementWorkspace.tsx`
  - `apps/oshun/web/src/components/studio/StudioIsisBudgetManagementRouteMap.ts`

## Automated coverage

- `apps/oshun/web/e2e/studio-isis-budget-management.spec.ts` drives the direct
  hard-block, localhost-only lane bypass, live BFF catalog, seeded
  `tenant-lotus` / `tenant-aurora` / `tenant-vesper` / `tenant-ember` verdicts,
  status filtering with local persistence, route-map, quick-actions, loading,
  service-failure, malformed, filtered-empty, unauthorized, network, anonymous
  redirect, 44px hit targets, and shared axe gate.
- `apps/oshun/bff/src/__tests__/admin-isis-budget-management-route.test.ts`
  covers auth/scope enforcement, real `evaluateBudget` status semantics across
  all four seeded tenant states, and status-count rollup.

## Cross-references

- Studio overview: [`../../studio-overview.md`](../../studio-overview.md)
- Sibling routes:
  - [`studio-isis-cost-tracking.md`](./studio-isis-cost-tracking.md)
  - [`studio-isis-resource-recommendations.md`](./studio-isis-resource-recommendations.md)
  - [`studio-isis-user-feedback-loop.md`](./studio-isis-user-feedback-loop.md)

## Open questions / known gaps

- [x] Read-only surface — arming/disarming a kill switch or editing a cap is not
      exposed here; confirm where envelopes are mutated
- [x] `projectedSpendCents` projection method is server-side; this view only
      renders the verdict
- [ ] Route-map sub-paths are declared but not yet implemented as separate pages
- [ ] Manual AT, real touch-device, offline replay, and telemetry-delivery
      passes remain product-hardening items beyond this automated route journey