V1 Web PWA · Surface walkthrough

Isis Job Envelope

A per-surface walkthrough of the V1 Web PWA studio surface: layout, states, interactions, data, and cross-references.

walked
9sections5 minread
Markdown source
On this page

Context. surface studio · domain isis · route /studio/isis/job-envelope · auth signed-in + studio entitlement; direct legacy Studio Isis route is boundary-hard-blocked unless the localhost-only E2E lane-bypass is present · source apps/oshun/web/src/app/studio/isis/job-envelope/page.tsx

Last walked. 2026-07-24 focused Chromium authority walk — production hard-block, localhost lane bypass, exact request-local normalization disposition, live form, five child lanes, honest route status, and applicable axe verified; prior 2026-07-01 live-infra state coverage retained

Purpose#

Request-local, non-authoritative field-normalization preview that also composes the Isis job-pipeline lanes into one surface. It embeds five sibling workspaces — job submission, job management, generation API, GPU worker, and workflow registry — each running its own lane. It also exposes a real envelope field-normalization lane backed by /v1/admin/isis/job-envelope and /v1/admin/isis/job-envelope/normalize, wiring the @isis/job-envelope control-field coercion layer into the Studio shell. Normalization does not validate a complete envelope, retain a job, dispatch work, retry, remediate, certify parity, create evidence, govern, approve, or authorize release.

Entry points#

  • Breadcrumb / quick-action card from /studio/isis/job-management
  • Studio index (/studio)
  • Direct URL / bookmark

Layout regions#

page.tsx mounts ShellLayout active="studio" with a breadcrumb panel.

  • Breadcrumb panel (data-isis-job-envelope-breadcrumbs): Studio → Isis Job Management → (current)
  • Workspace panel (data-isis-job-envelope-workspace):
    • <h1> "Isis Job Envelope Workspace" (WorkspaceHeading) + summary (data-isis-job-envelope-summary)
    • Exact request_local_non_authoritative_normalization_preview_with_embedded_lane_composition disposition and Authority Boundary panel (data-isis-job-envelope-capability-summary, <h2>)
    • Envelope Field Normalization lane (data-isis-job-envelope-normalization-lane): live catalog load, raw field inputs (data-isis-je-field), normalize submit (data-isis-je-normalize-submit), result table (data-isis-je-result), and fail-closed loading / unauthorized / error states
    • Five embedded lanes, each an <h2> panel wrapping a sibling workspace via WorkspaceSection:
      • Job Submission Lane (data-isis-job-envelope-job-submission-lane)
      • Job Management Lane (data-isis-job-envelope-job-management-lane)
      • Generation API Lane (data-isis-job-envelope-generation-api-lane)
      • GPU Worker Lane (data-isis-job-envelope-gpu-worker-lane)
      • Workflow Registry Lane (data-isis-job-envelope-workflow-registry-lane)
  • Route map panel (data-isis-job-envelope-route-map): one mounted-hybrid-tool and five documented-contract entries
  • Quick-actions panel: quickAction links to /studio/isis/job-submission, /studio/isis/job-management, /studio/isis/gpu-worker, and "Back to Studio workspace index" → /studio

States#

The normalization lane fetches its catalog and normalize result directly; each embedded lane drives its own Loading / Unauthorized (admin-scope 401/403) / Error / Ready / Result states.

  • Normalization lane Loading — data-isis-je-loading
  • Normalization lane Unauthorized — 401/403 admin-scope fail-closed; data-isis-je-unauthorized
  • Normalization lane Error — non-OK / malformed catalog; data-isis-je-error
  • Normalization lane Ready — field catalog + form (data-isis-je-normalize-form)
  • Normalization lane Result — alias/unresolved canonicalization table (data-isis-je-result, data-isis-je-counts)
  • Job Submission Lane shell — walk via studio-isis-job-submission.md
  • Job Management Lane shell — walk via studio-isis-job-management.md
  • Generation API Lane shell — walk via studio-isis-generation-api.md
  • GPU Worker Lane embed gate — non-AAA users see data-aaa-gate-blocked for gpu-worker; direct route remains boundary controlled. Walk via studio-isis-gpu-worker.md
  • Workflow Registry Lane shell — walk via studio-isis-workflow-registry.md

Interactions#

Embedded lanes#

  • Job Submission Lane shell
  • Job Management Lane shell
  • Generation API Lane shell
  • GPU Worker Lane AAA embed-gate
  • Workflow Registry Lane shell

Envelope Field Normalization#

  • Catalog load — GET /v1/admin/isis/job-envelope returns the fields and vocabularies used by the form
  • Normalize seeded aliases — submit the default raw envelope and render 7 resolved · 0 unresolved, including BLENDER_RENDER → blender-render, openpose → pose, and feature-map → cached-feature-map
  • Unknown token remains unresolved — editing ipAdapterMode to not-a-real-mode renders 6 resolved · 1 unresolved without fabricating a canonical value
  • Malformed normalization response — successful HTTP with a malformed body renders data-isis-je-normalize-error and no result table
  • Network failure — unreachable normalize POST renders a fail-closed error and no result table

Capability summary#

  • Capability cards — non-interactive

Route map#

  • Route-map articles ×6 — non-interactive path + purpose entries

Quick-actions#

  • Open Isis Job Submission workspace → /studio/isis/job-submission
  • Open Isis Job Management workspace → /studio/isis/job-management
  • Open Isis GPU Worker workspace → /studio/isis/gpu-worker
  • Back to Studio workspace index → /studio

Data & contracts#

  • Reads: GET /v1/admin/isis/job-envelope for field/vocabulary catalog; embedded lanes read their own /v1 endpoints
  • Writes: POST /v1/admin/isis/job-envelope/normalize with { fields: Record<string, string> }; embedded lanes write their own /v1 endpoints
  • Persistence: none for normalization inputs or results; the response is request-local and recomputable
  • Authority: no complete-envelope validation, enqueue, dispatch, retry, remediation, diagnostic/evidence record, parity certification, audit, governance, approval, or release action
  • Realtime: None
  • Caching: normalization lane and embedded lanes use client fetch on mount with no-store semantics
  • Auth: normalization lane and embedded admin lanes are admin-scoped and fail-closed; direct legacy route navigation is blocked by the Studio Isis proxy boundary, with localhost-only E2E bypass for route-journey coverage
  • Component sources:
    • apps/oshun/web/src/components/studio/StudioIsisJobEnvelopeWorkspace.tsx
    • apps/oshun/web/src/components/studio/StudioIsisJobEnvelopeNormalizationLane.tsx
    • apps/oshun/web/src/components/studio/StudioIsisJobEnvelopeRouteMap.ts

Cross-references#

Open questions / known gaps#

  • Envelope, dispatch, diagnostics, parity, and governance routes are documented shapes only, with no pages or corresponding authority
  • The route now has a real local lane beyond the embedded pipeline shells: job-envelope field normalization against the live BFF
  • Manual AT, real touch-device, offline replay, and telemetry-delivery passes remain product-hardening items beyond this automated route journey

Automated coverage#

  • apps/oshun/web/e2e/studio-isis-job-envelope.spec.ts drives the direct hard-block, localhost-only lane bypass, live BFF catalog + normalize calls, alias-heavy success path, unresolved-token path, loading/service-failure / malformed-catalog / malformed-normalization / network-failure states, non-admin fail-closed state, anonymous redirect, embedded lane shells, AAA embed-gate, route-map, quick-actions, 44px hit targets, and shared axe gate. The 2026-07-24 isolated authority case is green. The retained live-BFF cases currently receive 404 from the shared shell-auth BFF for all Isis admin routes; this is an environment route-state limitation, not a normalization assertion failure.
  • apps/oshun/bff/src/__tests__/admin-isis-job-envelope-route.test.ts covers the BFF route contract: auth/admin gating, canonical vocabularies, alias-to-canonical normalization across all fields, canonical pass-through, unresolved unknown tokens, and 400 responses for invalid payload shapes.