Studio Hathor · World Version Branching

Purpose#

Admin lane console for the real @hathor/pre-production multi-version timeline branch-diff engine. Describe a set of timeline versions (each a clip set plus duration / metadata-parity / approval-readiness metrics), pick a baseline and a candidate branch, and read back which clips were added, removed, and kept, plus the rounded metric deltas (added = candidate \ baseline, removed = baseline
candidate, shared = candidate ∩ baseline). Admin-scoped and fail-closed.

Entry points#

• Quick-action link from /studio/hathor/pre-production-project-management (this page links out to pre-production-project-management)
• Direct URL / bookmark — yes; alternates.canonical set
• Studio overview — see ../../studio-overview.md

Layout regions#

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

• Workspace <section data-hathor-world-version-branching-workspace>:
  • <h1> (WorkspaceHeading) "Hathor World Version Branching Workspace"
  • Summary <p data-hathor-world-version-branching-summary>
  • The compare form lane: data-hathor-wvb-compare-form
• Route Map panel (data-hathor-world-version-branching-route-map): <h2> "Route Map" + 5 entries from STUDIO_HATHOR_WORLD_VERSION_BRANCHING_ROUTE_MAP
• Quick-action lane: two Link.quickAction anchors — Pre-Production Project Management, Back to Studio workspace index

States#

• Loading — <p data-hathor-wvb-loading>
• Unauthorized — data-hathor-wvb-unauthorized on 401/403 (admin Hathor scope required); fail-closed
• Error — data-hathor-wvb-error on non-OK GET / malformed catalog
• Ready (form) — data-hathor-wvb-compare-form once the catalog loads
• Result — data-hathor-wvb-result after a 200 compare; data-hathor-wvb-parse-error (bad version lines) and data-hathor-wvb-compare-error (non-200)

Interactions#

Workspace body (compare form lane)#

• Versions — <textarea data-hathor-wvb-versions> (aria-label "timeline versions"), one per line: versionId | clip,clip | durationSec | parityPct | approvalPct
• Baseline — <select data-hathor-wvb-baseline>
• Candidate — <select data-hathor-wvb-candidate>
• Diff branches — <button data-hathor-wvb-compare-submit type="submit"> → POST /v1/admin/hathor/world-version-branching/compare
• Result — data-hathor-wvb-result-branches, data-hathor-wvb-added, data-hathor-wvb-removed, data-hathor-wvb-shared, and the deltas data-hathor-wvb-duration-delta, data-hathor-wvb-parity-delta, data-hathor-wvb-approval-delta

Route Map panel#

• 5 route entries — verify match with STUDIO_HATHOR_WORLD_VERSION_BRANCHING_ROUTE_MAP

Quick-action lane#

• "Open Hathor Pre-Production Project Management workspace" (→ /studio/hathor/pre-production-project-management)
• "Back to Studio workspace index" (→ /studio)

Data & contracts#

• Reads: GET /v1/admin/hathor/world-version-branching on mount
• Writes: POST /v1/admin/hathor/world-version-branching/compare
• Realtime: none
• Caching: client fetch on mount, cache: 'no-store'; buildBffAuthHeaders
• Auth/role check: admin-scoped fail-closed (401/403); behind the signed-in
  • studio proxy gate

Cross-references#

• Parent: ../../studio-overview.md
• Shell: ../../../shell/04-auth-session.md
• Sibling routes: ./studio-hathor-pre-production-project-management.md, ./studio-hathor-entity-version-management.md
• Component sources:
  • apps/oshun/web/src/components/studio/StudioHathorWorldVersionBranchingWorkspace.tsx
  • apps/oshun/web/src/components/studio/StudioHathorWorldVersionBranchingRouteMap.ts

Open questions / known gaps#

• Hathor is unconfirmed-v1 per WALKTHROUGH/matrix/routes.csv. Confirm whether the dedicated /studio/hathor/* admin lane consoles ship in V1.
• The engine computes a two-branch set diff only; confirm whether N-way merge or conflict resolution is planned given the route's merges/ sub-route.
• Route Map advertises branches/, merges/, releases/, and governance/ sub-routes with no page.tsx yet.