Studio · Yemaya · Budget Management

Purpose#

Admin lane console that wires the real @yemaya/budget-management quality/budget/time ("iron triangle") optimizer: pick an optimization strategy and stakeholder weights and get the deterministic score, the cost / time / quality impacts, and concrete recommendations for a production budget.

Entry points#

• Studio index quick-actions.
• No breadcrumb panel on this page.
• Reachable from /studio/yemaya/crew-management (which links here); this page links out to /studio/yemaya/scheduling.
• Direct URL / bookmark (signed-in + studio entitlement).

Layout regions#

page.tsx renders ShellLayout active="studio" and:

• Workspace panel (StudioYemayaBudgetManagementWorkspace, data-yemaya-budget-management-workspace):
  • <h1> "Yemaya Budget Management Workspace".
  • Summary <p data-yemaya-budget-management-summary>: "Run the production iron-triangle optimizer — pick a strategy and stakeholder weights to see the cost / time / quality impacts and the concrete recommendations."
  • Optimize lane — loading / unauthorized / error / ready-form / pending submit / result.
• Route Map panel (data-yemaya-budget-management-route-map): <h2> "Route Map" with five entries (data-yemaya-budget-management-route-map-entry, data-route-path).
• Quick-action panel (data-yemaya-budget-management-quick-actions): two quickAction links with per-action selectors.

States#

• Loading — data-yemaya-bm-loading ("Loading optimizer…") before the catalog GET resolves.
• Unauthorized — 401/403 → data-yemaya-bm-unauthorized ("Access restricted.") with reason "Yemaya workspace scope required to view budget management.".
• Error — non-OK / malformed catalog → data-yemaya-bm-error.
• Ready-form — strategy <select> populated from catalog.strategies (labels mapped via STRATEGY_LABELS: minimize-cost / minimize-time / maximize-quality / balanced).
• Pending submit — data-yemaya-bm-optimize-form flips data-yemaya-bm-optimize-state="optimizing" / aria-busy="true" and data-yemaya-bm-optimize-submit disables with data-yemaya-bm-submit-state="optimizing" until the POST resolves.
• Result — 200 → data-yemaya-bm-result with data-yemaya-bm-score, data-yemaya-bm-impacts, data-yemaya-bm-weights, data-yemaya-bm-recommendations.
• Validation error — negative/non-finite weights or a sum ≤ 0, or a non-200 POST, render data-yemaya-bm-optimize-error ("Stakeholder weights must be non-negative and sum to more than zero.").

Interactions#

Optimize lane#

<form data-yemaya-bm-optimize-form>:

• Optimization strategy — <select data-yemaya-bm-field-strategy>.
• Cost weight — <input data-yemaya-bm-field-cost> (aria-label "cost weight").
• Time weight — <input data-yemaya-bm-field-time> (aria-label "time weight").
• Quality weight — <input data-yemaya-bm-field-quality> (aria-label "quality weight").
• "Run optimizer" submit (data-yemaya-bm-optimize-submit) — POSTs { strategy, weights: { cost, time, quality } }.

Route map#

data-yemaya-budget-management-route-map — five entries:

• /studio/yemaya/budget-management
• /studio/yemaya/budget-management/scenes/[sceneId]
• /studio/yemaya/budget-management/exports/[exportId]
• /studio/yemaya/budget-management/revisions/[revisionId]
• /studio/yemaya/budget-management/governance/[policyId]

Quick actions#

• "Open Yemaya Scheduling workspace" → /studio/yemaya/scheduling.
• "Back to Studio workspace index" → /studio.

Data & contracts#

• Reads: GET /v1/admin/yemaya/budget-management (catalog; strategies) on mount with buildBffAuthHeaders(), cache: 'no-store'.
• Writes: POST /v1/admin/yemaya/budget-management/optimize → { optimization: { result: { strategy, score, costSavings, timeImpact, qualityImpact, recommendations }, normalizedWeights, constraints } }.
• Realtime: None.
• Caching: client fetch on mount, no-store; aborted on unmount.
• Auth/role check: admin-scoped, fail-closed; route additionally signed-in + studio via the proxy gate.

Automated coverage#

• apps/oshun/web/e2e/studio-yemaya-budget-godot.spec.ts opens the page in the real Next shell, forwards browser /v1/admin/yemaya/budget-management GET and /optimize POST requests to the live local BFF with the page's bearer token, and asserts the exact balanced optimizer score (0.85), impacts, normalized weights, recommendations, auth headers, and submitted body.
• The same spec covers anonymous redirect, non-admin 403 rendering, controlled loading/503 catalog failure, local zero-sum weight validation with zero POSTs, BFF write-error surfacing, pending-submit lockout, route-map entries, quick-action hrefs, mobile no-overflow, 44 px controls, and direct BFF 401/403/400/200 contract gates.

Cross-references#

• Workspace source: apps/oshun/web/src/components/studio/StudioYemayaBudgetManagementWorkspace.tsx
• Route map source: apps/oshun/web/src/components/studio/StudioYemayaBudgetManagementRouteMap.ts
• Page source: apps/oshun/web/src/app/studio/yemaya/budget-management/page.tsx
• Sibling: studio-yemaya-crew-management.md
• Studio overview: studio-overview.md
• Feature spec: V1/features.md

Open questions / known gaps#

• The route-map children (scenes/exports/revisions/governance) are a sitemap contract; verify which dynamic pages exist.
• The optimizer is stateless (no persisted budget ledger); confirm whether a saved-scenario store is planned.