---
path: /studio/aja/performance-optimization
surface: studio
domain: aja
auth: signed-in + studio entitlement
source: apps/oshun/web/src/app/studio/aja/performance-optimization/page.tsx
status: walked + e2e-covered
last_walked:
  '2026-07-04 focused real-dev-infra Playwright route walk — anonymous redirect,
  Aja-admin quantization catalog, exact default symmetric and edited asymmetric
  quantization through the real BFF, local/BFF validation, malformed/transport
  failures, loading/403/503/malformed catalog states, pending controls,
  route-map + quick-action affordances, mobile/touch/axe, and direct BFF
  auth/schema gates. Evidence:
  WALKTHROUGH/results/v1-real-infra-run-2026-06-22.md §286.'
---

# Studio Aja · Performance Optimization

## Purpose

Admin lane console for weight quantization. Its operations lane wires
`@aja/model-optimization` quantization primitives via
`/v1/admin/aja/performance-optimization`: calibrate the quant parameters
(scale + zero-point) from a value range, quantize each value to a chosen bit
width (symmetric or asymmetric), dequantize back, and read the reconstruction
error (fidelity cost) and compression ratio.

## Entry points

- **Direct URL / bookmark** — `/studio/aja/performance-optimization`; metadata
  sets `alternates.canonical`
- **Linked from `/studio`** Domain-bridge studios section (Aja sub-area)
- **Quick action** — "Open Aja Distributed Processing workspace"
  (`/studio/aja/distributed-processing`)

## Layout regions

`page.tsx` renders inside `<ShellLayout active="studio">`:

- **Workspace** `StudioAjaPerformanceOptimizationWorkspace` — `<h1>` "Aja
  Performance Optimization Workspace" + summary
  (`data-aja-performance-optimization-summary`), a **Capability Summary** panel
  (`data-aja-performance-optimization-capability-summary`, 4 cards), then the
  **Performance Optimization Operations Lane**
  (`data-aja-performance-optimization-operations-lane`)
- **Route Map panel** (`data-aja-performance-optimization-route-map`, `<h2>`) —
  5 entries from `STUDIO_AJA_PERFORMANCE_OPTIMIZATION_ROUTE_MAP`, exposed with
  `data-aja-performance-optimization-route-map-entry` / `data-route-path`.
- **Quick-action lane** (`data-aja-performance-optimization-quick-actions`) —
  `quickAction` links: distributed-processing, `/studio`.

## States

- [x] **Loading** — `data-aja-po-loading` "Loading quantization technique..."
      while `GET /v1/admin/aja/performance-optimization` is in flight.
- [x] **Unauthorized (gated)** — `data-aja-po-unauthorized` on 401/403; admin
      scope message ("Aja workspace scope required to run quantization.").
- [x] **Error** — `data-aja-po-error` on non-OK / malformed / network failure.
- [x] **Ready (form)** — `data-aja-po-form`, catalog attributes
      (`data-aja-po-technique`, mode/report counts and spans), and idle submit
      state once the catalog loads.
- [x] **Result** — `data-aja-po-result` with stable bit-width / symmetry / range
      / scale / zero-point / error / compression attributes,
      `data-aja-po-headline`, `data-aja-po-params`, `data-aja-po-quantized`, and
      `data-aja-po-dequantized`.
- [x] **Validation error** — `data-aja-po-quantize-error`.
- [x] **Offline** — SSR shell; lane error state when `fetch` unavailable.
- [x] **Standalone PWA** — desktop layout; `quickAction` anchors wrap.
- [x] **Empty** — N/A; capability cards + route map are constant

## Interactions

### Performance Optimization Operations Lane

- [x] **Weight values** (`<input data-aja-po-values>`, label "weight values") —
      comma-separated numbers
- [x] **Bit width** (`<input data-aja-po-bits>`, label "bit width") — integer
      2–16
- [x] **Symmetric** (`<input data-aja-po-symmetric type="checkbox">`, label
      "symmetric") — zero-point fixed at 0 when checked
- [x] **"Quantize"** (`<button data-aja-po-submit>`) — POSTs
      `{ values, numBits, symmetric }` to
      `/v1/admin/aja/performance-optimization/quantize`; locked with
      `data-aja-po-submit-state="quantizing"` while the real request is pending.

### Capability Summary panel

- [x] **4 cards** (`data-aja-performance-optimization-capability=<id>`):
      `optimization-control-plane`, `diagnostics-and-trace-observability`,
      `security-permission-audit-controls`, `api-parity-and-contract-assurance`
      — non-interactive

### Route Map panel

- [x] **5 entries** (`<article>` per `path` + `purpose`) — non-interactive

### Quick-action lane

- [x] **"Open Aja Distributed Processing workspace"** →
      `/studio/aja/distributed-processing`
- [x] **"Back to Studio workspace index"** → `/studio`

## Data & contracts

- **Reads**: `GET /v1/admin/aja/performance-optimization` (catalog: `technique`,
  `summary`, `modes`, `reports`) on mount, `cache: 'no-store'`,
  `buildBffAuthHeaders()`. Client fails closed unless the expected
  `quantization` technique, both modes, and all seven report keys are present.
- **Writes**: `POST /v1/admin/aja/performance-optimization/quantize` →
  `{ numBits, symmetric, min, max, scale, zeroPoint, quantized, dequantized, meanAbsError, maxAbsError, compressionRatio }`.
  Client fails closed unless all scalar metrics are finite numbers and the
  quantized/dequantized arrays are present with matching lengths.
- **Realtime**: none
- **Caching**: client fetch on mount (no-store); SSR shell
- **Auth/role check**: BFF endpoints admin-scoped, fail-closed (401/403 →
  unauthorized render); route gated signed-in + studio via the proxy

## Cross-references

- Parent: [`../../studio-overview.md`](../../studio-overview.md)
- Sibling routes:
  [`./studio-aja-distributed-processing.md`](./studio-aja-distributed-processing.md)
- Component sources:
  - `apps/oshun/web/src/components/studio/StudioAjaPerformanceOptimizationWorkspace.tsx`
  - `apps/oshun/web/src/components/studio/StudioAjaPerformanceOptimizationRouteMap.ts`

## Verification evidence

- `apps/oshun/web/e2e/studio-aja-performance-optimization.spec.ts` runs against
  the real Next Studio shell and local BFF, forwarding browser bearer auth
  rather than mocking the quantization contract.
- The spec covers anonymous redirect, Aja-admin catalog load, exact default
  8-bit symmetric quantization, edited 8-bit asymmetric quantization, local
  validation with no POST, BFF detail surfacing, malformed result, transport
  failure, loading / 503 / malformed / non-admin states, pending form locking,
  mobile no-overflow + 44px controls, scoped axe, and direct BFF 401/403/400/200
  gates.

## Open questions / known gaps

- [ ] The 4 Capability Summary cards are descriptive copy only — the single live
      affordance is the quantization lane
- [ ] Route Map lists `scenes`/`exports`/`revisions`/`governance` child routes
      that are not yet implemented as pages.