---
path: /studio/isis/workflow-versioning
surface: studio
domain: isis
auth: signed-in + studio entitlement (NOT AAA-gated)
source: apps/oshun/web/src/app/studio/isis/workflow-versioning/page.tsx
status: walked
last_walked:
  '2026-05-29 automated runtime walk (Playwright headless) — render, /v1 data
  (2xx), console/page-errors, expected content, screenshot verified; live
  screen-reader, touch, offline, and telemetry-delivery checks pending a manual
  AT pass. Evidence: WALKTHROUGH/results/runtime-sweep-2026-05-29.md; body
  re-derived 2026-06-03 from current source (lane-console architecture);
  2026-06-30 addendum: `studio-isis-workflow-versioning.spec.ts` proved the
  direct route remains hard-blocked by the Studio Isis boundary, then drove the
  localhost-only lane-bypass route against the real local BFF, including the
  manifest-backed 48-workflow registry, schema/range metadata,
  older/newer/invalid version comparisons, real behind-only empty filtering,
  loading/empty/error/malformed/compare-network-failure/unauthorized/anonymous
  states, route-map articles, sibling quick-actions, and 44px automated
  hit-target checks for compare controls, the filter target, and quick-actions.'
---

# Isis Workflow Versioning

## Purpose

Admin read-only lane console over the real `@isis/workflows` registry + semver
versioning functions via `GET /v1/admin/isis/workflow-versioning`: it shows each
workflow's parsed version, the latest version in its category, and a
current/behind verdict; the active schema version + compatibility range; and a
version-compare tool. It is admin-scoped and fails closed.

## Entry points

- Sibling quick-action from `/studio/isis/workflow-definitions`
- Studio index (`/studio`)
- Direct URL / bookmark

## Layout regions

`page.tsx` mounts `<ShellLayout active="studio">` (no breadcrumb panel) and
three panels: the workspace, the Route Map, and sibling quick-actions.

- **Header**: shell header
- **Workspace panel** (`data-isis-workflow-versioning-workspace`):
  - `<h1>` (`WorkspaceHeading`) "Isis Workflow Versioning Workspace"
  - Summary paragraph (`data-isis-workflow-versioning-summary`)
  - Active schema version + compatibility range (`data-versioning-schema`)
  - Version-compare tool (`data-versioning-compare`)
  - Workflow list (`data-versioning-list`, each `data-versioning-entry` with
    `data-versioning-entry-status=latest|behind`); empty state
    `data-versioning-empty`; behind-only filter `data-versioning-behind-filter`
- **Route Map panel** (`data-isis-workflow-versioning-route-map`):
  `<h2>Route Map</h2>` over `STUDIO_ISIS_WORKFLOW_VERSIONING_ROUTE_MAP` (5
  entries)
- **Sibling quick-actions panel**: `/studio/isis/workflow-definitions`,
  `/studio`

## States

- [x] **Loading** — `data-versioning-loading`
- [x] **Unauthorized** — 401/403 admin-scope fail-closed;
      `data-versioning-unauthorized`
- [x] **Error** — non-OK or malformed response; `data-versioning-error`
- [x] **Ready** — registry present; schema + compare + list render
- [x] **Empty** — zero-entry catalog renders no fabricated workflow rows and the
      empty list message
- [x] **Compare result** — after a compare query,
      `data-versioning-compare-result`
- [x] **Compare error** — invalid semver or request failure renders
      `data-versioning-compare-error`

## Interactions

### Version-compare tool (`data-versioning-compare`)

- [x] **Version A** (`data-versioning-compare-a`, text input)
- [x] **Version B** (`data-versioning-compare-b`, text input)
- [x] **Compare** (`data-versioning-compare-submit`, button; "Comparing…" while
      in flight) — re-issues
      `GET /v1/admin/isis/workflow-versioning?compareA=…&     compareB=…` and
      renders `data-versioning-compare-result`

### Filter

- [x] **Behind-only filter** (`data-versioning-behind-filter`) — narrows the
      list to behind entries

### Route Map

- [x] **Route-map articles** ×5

### Sibling quick-actions

- [x] **Open Isis Workflow Definitions workspace** →
      `/studio/isis/workflow-definitions`
- [x] **Back to Studio workspace index** → `/studio`

## Data & contracts

- **Reads**: `GET /v1/admin/isis/workflow-versioning` (per-workflow version +
  latest + current/behind verdict; active schema; comparison via `compareA` /
  `compareB` query params)
- **Writes**: none — this is a read-only versioning browser; the compare tool is
  a parameterized GET, not a mutation
- **Realtime**: none
- **Caching**: client fetch on mount, `cache: 'no-store'`,
  `buildBffAuthHeaders()`
- **Auth/role check**: admin-scoped, fail-closed (401/403); route gated on
  signed-in + studio entitlement
- **Component sources**:
  - `apps/oshun/web/src/components/studio/StudioIsisWorkflowVersioningWorkspace.tsx`
  - `apps/oshun/web/src/components/studio/StudioIsisWorkflowVersioningRouteMap.ts`

## E2E coverage

- [`apps/oshun/web/e2e/studio-isis-workflow-versioning.spec.ts`](../../../../apps/oshun/web/e2e/studio-isis-workflow-versioning.spec.ts)
  — proves direct `/studio/isis/workflow-versioning` is still hard-blocked by
  the Studio Isis boundary, then drives the localhost-only
  `?__oshunStudioIsisLaneE2E=1` lane bypass in the real Next shell with browser
  requests forwarded to the real local BFF. Covered paths:
  - Admin lane-bypass navigation loads the real `@isis/workflows` registry:
    schema `1.0.0`, compatibility range `^1.0.0`, 48 workflow rows, behind count
    `0`, representative `artifact-reconstruction` and `music-cue-composer`
    entries, route-map articles, sibling quick-actions, and bearer-authenticated
    catalog request.
  - The compare tool reissues live parameterized GET requests for
    `1.0.0 -> 2.0.0` (`older`, satisfies range), `2.0.0 -> 1.0.0` (`newer`, does
    not satisfy range), and invalid `not-semver` input, proving both result and
    fail-closed error paths.
  - Behind-only filtering renders the real empty state because the current
    registry has no behind rows; loading, empty catalog, 503 error, malformed
    catalog, compare network failure, non-admin unauthorized, anonymous
    redirect-before-render, and automated 44px hit-target checks are asserted.

## Cross-references

- Studio overview: [`../../studio-overview.md`](../../studio-overview.md)
- Sibling routes:
  - [`studio-isis-workflow-definitions.md`](./studio-isis-workflow-definitions.md)
  - [`studio-isis-workflow-registry.md`](./studio-isis-workflow-registry.md)
  - [`studio-isis-workflow-templates.md`](./studio-isis-workflow-templates.md)

## Open questions / known gaps

- [ ] No breadcrumb on this route — navigation is via sibling quick-actions
- [ ] Route-map sub-paths are declared but not yet implemented as separate pages
- [ ] Live screen-reader, touch-device, offline/PWA-cache, and
      telemetry-delivery passes still need a manual or dedicated-device run;
      automated coverage includes Playwright role/locator checks, explicit 44px
      hit-target measurements, and the suite-wide axe pass.