Studio Hathor · World Configuration

Purpose#

Dense operator workspace for governing canonical world-configuration records — continuity guardrails, governance gates, and publication readiness for narrative-scale production. Unlike the sibling Hathor admin lanes, this is the older dense-operator surface: it hydrates records from the BFF on mount (falling back to seeded INITIAL_WORLD_CONFIGURATION_RECORDS) and exposes list/detail, wizard, policy, collaboration, observability, parity, and production-signoff panels in one client component.

Entry points#

• Direct URL / bookmark — /studio/hathor/world-configuration; alternates.canonical is set.
• Quick-action from siblings — the Database and Event Handlers pages link here; this page links out to a set of related Hathor world lanes and downstream Bellona consumers.
• Studio overview — see ../../studio-overview.md.

Layout regions#

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

• Workspace (StudioHathorWorldConfigurationWorkspace, data-hathor-world-configuration-workspace, aria-label="Hathor world configuration workspace"):
  • <h1> WorkspaceHeading — "Hathor World Configuration Workspace" + summary <p>.
  • Navigation Contract (data-hathor-world-configuration-navigation-contract, <h2>): renders STUDIO_HATHOR_WORLD_CONFIGURATION_ROUTE_MAP (5 entries).
  • Execution Milestones (data-hathor-world-configuration-milestones).
  • Policy Controls (data-hathor-world-configuration-policy-controls): role / tier / justification selectors gating writes.
  • List/detail (data-hathor-world-configuration-list-view / -detail-view): search, scope/status filters, sort, select + bulk actions, saved views; detail timeline, diagnostics, related entities.
  • Wizard (data-hathor-world-configuration-wizard): create/edit form with templates and a policy tier.
  • Command palette (data-hathor-world-configuration-command-palette), stream (-stream-*), collaboration (-collab-*), audit/change history (-audit-* / -change-history-*), telemetry (-telemetry-*), observability (-observability-*), import/export (-import-export-*), API parity (-api-parity-*), docs (-docs-*), and production readiness/signoff (-production-*) panels.
• Route Map panel (<section data-hathor-world-configuration-route-map>, <h2>Route Map</h2>): 5 entries from STUDIO_HATHOR_WORLD_CONFIGURATION_ROUTE_MAP.
• Related Hathor world lanes panel (<section data-hathor-world-configuration-related-hathor>, <h2>): quick links to World API, World Version Branching, Geography Modeling, Location Modeling, Culture Modeling, Faction Modeling.
• Downstream engine integration panel (<section data-hathor-world-configuration-downstream>, <h2>): labelled cross-domain links to Bellona C++ SDK and Lore-to-Engine Compilation (downstream consumers).
• Back-to-Studio panel (className="quickAction" Link → /studio).

States#

• Records hydration — on mount, GET the records endpoint; if it returns a non-empty array, adopt it, otherwise keep INITIAL_WORLD_CONFIGURATION_RECORDS (empty / 401 / offline / failure all fall back).
• List populated / filtered — scope/status filters + search + data-hathor-world-configuration-list-row rows.
• Policy-gated — viewer role and restricted tier without justification block reads/writes with reason strings (data-hathor-world-configuration-policy-*-empty-state).
• Wizard open (create/edit) — gated by wizardWrite permission.
• Parity / observability — parity report (data-hathor-world-configuration-api-parity-overall) and refreshable observability metrics; production gate requires checklist + parity + observability.

Interactions#

• Policy — data-hathor-world-configuration-policy-role / -policy-tier / -policy-justification set the write-permission context.
• List — data-hathor-world-configuration-search, -scope-filter, -status-filter, -sort-key, -sort-direction, -select-all-visible, -row-toggle-select, and bulk actions (-bulk-set-stable / -bulk-set-blocked / -bulk-assign-world-ops); saved views (-saved-view-save / -saved-view-apply).
• Wizard — -wizard-open-create / -wizard-open-edit, the form fields, -wizard-apply-template, -wizard-save, -wizard-cancel.
• Import/export — -import-export-export / -import-export-apply.
• API parity — -api-parity-run; observability — -observability-refresh; production signoff — -production-signoff-approve / -production-signoff-revoke.
• Route Map entries — verify against STUDIO_HATHOR_WORLD_CONFIGURATION_ROUTE_MAP (5 entries).
• Related / downstream links — the related-Hathor and downstream-Bellona quick links.

Data & contracts#

• Reads: GET /v1/studio/hathor/world-configuration/records on mount ({ records }; fail-soft fallback to seeded records).
• Writes: POST /v1/studio/hathor/world-configuration/records (best-effort, keepalive, fire-and-forget — a failed write never blocks the wizard); all other mutations (filters, wizard, collaboration, telemetry, snapshots) are client-side state.
• Realtime: a client-side stream monitor (pulse/reconnect counters); no live channel.
• Caching: client fetch on mount, cache: 'no-store', buildBffAuthHeaders(); shell-state preferences persist via useStudioWorkspacePersistence.
• Auth: route is behind the signed-in + studio proxy gate; record reads are attempted with BFF auth headers.

Cross-references#

• Parent: ../../studio-overview.md
• Component sources:
  • apps/oshun/web/src/components/studio/StudioHathorWorldConfigurationWorkspace.tsx (dense-operator workspace; the only Hathor surface still on this template)
  • apps/oshun/web/src/components/studio/StudioHathorWorldConfigurationRouteMap.ts
• Embedded by: ./studio-hathor-database.md
• Related Hathor world lanes: ./studio-hathor-world-api.md, ./studio-hathor-world-version-branching.md, ./studio-hathor-geography-modeling.md, ./studio-hathor-location-modeling.md
• Downstream Bellona consumers: /studio/bellona/cpp-sdk, /studio/bellona/lore-to-engine-compilation

Open questions / known gaps#

• This is the last Hathor surface on the legacy dense-operator template (fixtures + command palette + wizard + telemetry + parity panels); confirm whether it should be reduced to a single real-backed lane like its siblings.
• Record writes are best-effort fire-and-forget; confirm whether the BFF records endpoint should become an authoritative, awaited persistence path.
• Hathor is unconfirmed-v1 per WALKTHROUGH/matrix/routes.csv; confirm whether the dedicated /studio/hathor/* surfaces ship V1 or are internal-only.