Studio Hathor · Entity Version Management

Purpose#

Admin lane console that assesses a set of entity versions for lineage, branch, metadata, and approval health and returns a verdict with prioritized findings. The operator picks an assessment mode and priority, sets active/baseline version ids and per-axis percentage thresholds, supplies a JSON array of versions, and the lane scores them and lists findings.

Entry points#

• Quick-action link from /studio/hathor/world-version-branching (verify against that page's source)
• Direct URL / bookmark — yes; alternates.canonical set to /studio/hathor/entity-version-management
• Studio overview — see ../../studio-overview.md

Layout regions#

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

• Workspace <StudioHathorEntityVersionManagementWorkspace /> (data-hathor-entity-version-management-workspace):
  • WorkspaceHeading <h1> — "Hathor Entity Version Management Workspace"
  • Summary <p data-hathor-entity-version-management-summary>
  • The assessment form lane (loading / unauthorized / error / form / result)
• Route Map panel data-hathor-entity-version-management-route-map — <h2> "Route Map" listing the 5 STUDIO_HATHOR_ENTITY_VERSION_MANAGEMENT_ROUTE_MAP entries (entities / changesets / reconciliations / governance child paths)
• Quick-action lane — two Link.quickAction anchors: World Version Branching, Back to Studio workspace index

States#

• Loading — data-hathor-evm-loading while the GET catalog request is in flight
• Unauthorized (admin-scope 401/403) — data-hathor-evm-unauthorized with reason
• Error — data-hathor-evm-error with reason
• Ready (form) — mode/priority selects, threshold inputs, versions textarea, submit
• Result — data-hathor-evm-result with data-hathor-evm-verdict, data-hathor-evm-scores, data-hathor-evm-findings (list of data-hathor-evm-finding carrying data-hathor-evm-priority), or data-hathor-evm-no-findings
• Validation error — data-hathor-evm-assess-error

Interactions#

Assessment lane#

• Mode — <select data-hathor-evm-mode> (<span>Mode</span>)
• Priority — <select data-hathor-evm-priority> (<span>Priority</span>)
• Lineage % / Branch % / Metadata % / Approval % — threshold inputs
• Active version id / Baseline version id — data-hathor-evm-active, data-hathor-evm-baseline
• Versions (JSON array) — versions textarea
• Submit — <button data-hathor-evm-submit> "Assess versions" → POST ASSESS_ENDPOINT

Route Map panel#

• Route entries — verify match with STUDIO_HATHOR_ENTITY_VERSION_MANAGEMENT_ROUTE_MAP (5 entries)

Quick-action lane#

• "Open Hathor World Version Branching workspace" → /studio/hathor/world-version-branching
• "Back to Studio workspace index" → /studio

Data & contracts#

• Reads: GET /v1/admin/hathor/entity-version-management (EVM_ENDPOINT) — the assessment catalog (modes, priorities, defaults)
• Writes: POST /v1/admin/hathor/entity-version-management/assess (ASSESS_ENDPOINT) with the version board + thresholds
• Realtime: none
• Caching: client fetch on mount, cache: 'no-store', buildBffAuthHeaders()
• Auth/role check: admin-scoped, fail-closed on 401/403; route additionally gated signed-in + studio by the BFF proxy

Cross-references#

• Parent: ../../studio-overview.md
• Shell: ../../../shell/04-auth-session.md
• Sibling routes: ./studio-hathor-world-version-branching.md
• Component sources:
  • apps/oshun/web/src/components/studio/StudioHathorEntityVersionManagementWorkspace.tsx
  • apps/oshun/web/src/components/studio/StudioHathorEntityVersionManagementRouteMap.ts

Open questions / known gaps#

• Hathor is unconfirmed-v1 per WALKTHROUGH/matrix/routes.csv. Confirm whether the dedicated /studio/hathor/ lane consoles ship at V1 or are internal-only.
• Confirm the expected JSON schema for the versions array (the form only hints "JSON array"); a schema link in the lane would reduce 400s.