Studio Aja · Job Lifecycle

Purpose#

Admin lane console for the real @aja/distributed-workers fault-tolerance helpers. The operator picks a failed task's status and supplies its retry count and retry budget; the lane decides recovery (retry vs. permanently fail) against the budget and computes the exponential-backoff delay before the next attempt (flagging when the delay is capped).

Entry points#

• Direct URL / bookmark — /studio/aja/job-lifecycle; metadata canonical to this path
• Studio nav — Domain-bridge studios section of /studio
• Sibling quick-actions on this page: Configuration Formats, Back to Studio (no breadcrumb panel on this route)
• Operator surfacing — see ../../studio-overview.md

Layout regions#

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

• Workspace (<StudioAjaJobLifecycleWorkspace />, archetype: LEAF):
  • <h1> (WorkspaceHeading) "Aja Job Lifecycle Workspace"
  • Summary <p data-aja-job-lifecycle-summary> — operations lane decides task recovery and computes the retry backoff on the real fault-tolerance engine
  • Task Recovery Operations Lane (<h2 data-aja-jl-lane-heading> "Task Recovery Operations Lane") — the live evaluate form
• Route Map panel (data-aja-job-lifecycle-route-map): <h2>Route Map</h2> listing 5 entries from STUDIO_AJA_JOB_LIFECYCLE_ROUTE_MAP (primary, scenes, exports, revisions, governance)
• Quick-action panel: two Link.quickAction anchors — Configuration Formats, Back to Studio workspace index

States#

• Loading — GETs the engine catalog on mount; renders <p data-aja-jl-loading> "Loading fault-tolerance engine…"
• Unauthorized — 401/403 renders data-aja-jl-unauthorized ("Access restricted." + admin-scope message, default "Aja workspace scope required to evaluate job lifecycle.")
• Error — non-OK / malformed / unreachable renders data-aja-jl-error ("Could not load the fault-tolerance engine." + reason)
• Ready (form) — success renders data-aja-jl-engine-summary and the data-aja-jl-form
• Result — a successful POST renders data-aja-jl-result with data-aja-jl-headline (permanently fail / retry in N ms (capped) / no recovery needed · retry count/max)
• Validation / evaluate error — client guards (retry count and max retries non-negative integers) and POST failures render data-aja-jl-evaluate-error
• Empty / Standalone PWA / offline — N/A beyond the above; shell SSR, lane is a client fetch on mount

Interactions#

Operations lane (data-aja-jl-form)#

• Task status (data-aja-jl-status, select, label "Task status") — options from the catalog's taskStatuses
• Retry count (data-aja-jl-retry, number input, aria-label "retry count")
• Max retries (data-aja-jl-max, number input, aria-label "max retries")
• "Evaluate recovery" (data-aja-jl-submit, submit) — posts task status, retry count, and max retries to /v1/admin/aja/job-lifecycle/evaluate

Route Map panel#

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

Quick-action panel#

• "Open Aja Configuration Formats workspace" → /studio/aja/configuration-formats
• "Back to Studio workspace index" → /studio

E2E coverage#

• apps/oshun/web/e2e/studio-aja-job-queue-lane-consoles.spec.ts covers signed-in shell render, ready recovery form, negative retry-count client guard with no POST, real BFF retry/backoff output (retry in 2000ms · retry 1/3), exhausted-budget permanent-fail output, route-map count, exact quick-action hrefs, 44 px submit target, loading / unauthorized / malformed-catalog fail-closed states, mobile no-overflow, and direct BFF auth/schema/happy-path gates.

Data & contracts#

• Reads: GET /v1/admin/aja/job-lifecycle on mount — catalog { summary, taskStatuses: string[], retryBackoff: { baseDelayMs, maxDelayMs } }
• Writes: POST /v1/admin/aja/job-lifecycle/evaluate — { status, retryCount, maxRetries } → { result } (status, retryCount, maxRetries, needsRecovery, shouldFail, nextRetryDelayMs, retryDelayCapped)
• Realtime: none
• Caching: client fetch on mount with cache: 'no-store' and buildBffAuthHeaders(); SSR shell only
• Auth/role check: BFF endpoints admin-scoped + fail-closed (401/403 → unauthorized render); route behind the signed-in + studio proxy gate

Cross-references#

• Parent: ../../studio-overview.md
• Shell: ../../../shell/04-auth-session.md
• Sibling routes: ./studio-aja-configuration-formats.md
• Component sources:
  • apps/oshun/web/src/components/studio/StudioAjaJobLifecycleWorkspace.tsx
  • apps/oshun/web/src/components/studio/StudioAjaJobLifecycleRouteMap.ts

Known downstream boundaries#

• Route-map sub-routes are descriptive contracts; implementation status of those child pages is tracked separately from this leaf console.