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#

• Loading — data-aja-po-loading "Loading quantization technique..." while GET /v1/admin/aja/performance-optimization is in flight.
• Unauthorized (gated) — data-aja-po-unauthorized on 401/403; admin scope message ("Aja workspace scope required to run quantization.").
• Error — data-aja-po-error on non-OK / malformed / network failure.
• 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.
• 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.
• Validation error — data-aja-po-quantize-error.
• Offline — SSR shell; lane error state when fetch unavailable.
• Standalone PWA — desktop layout; quickAction anchors wrap.
• Empty — N/A; capability cards + route map are constant

Interactions#

Performance Optimization Operations Lane#

• Weight values (<input data-aja-po-values>, label "weight values") — comma-separated numbers
• Bit width (<input data-aja-po-bits>, label "bit width") — integer 2–16
• Symmetric (<input data-aja-po-symmetric type="checkbox">, label "symmetric") — zero-point fixed at 0 when checked
• "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#

• 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#

• 5 entries (<article> per path + purpose) — non-interactive

Quick-action lane#

• "Open Aja Distributed Processing workspace" → /studio/aja/distributed-processing
• "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
• Sibling routes: ./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.