Studio Hathor · Culture Modeling

Purpose#

Admin lane console that runs the real @hathor/domain-models cultural-compatibility and social-analysis algorithms against two supplied cultures. The operator submits a JSON pair (cultureA / cultureB) and the lane returns compatibility, dominant value category, numeric social mobility, and inequality-index metrics. The catalog (social structures, attitudes) is fetched once on mount to ground the form.

Entry points#

• Quick-action link from /studio/hathor/legal-systems-modeling — "Open Hathor Culture Modeling workspace" (verify against that page's source)
• Direct URL / bookmark — yes; alternates.canonical set to /studio/hathor/culture-modeling
• Studio overview — see ../../studio-overview.md

Layout regions#

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

• Workspace <StudioHathorCultureModelingWorkspace /> (data-hathor-culture-modeling-workspace):
  • WorkspaceHeading <h1> — "Hathor Culture Modeling Workspace"
  • Summary <p data-hathor-culture-modeling-summary> describing the compatibility / dominant-value / social-mobility / inequality outputs
  • Cultural Compatibility Lane — <h2 data-culture-lane-heading>; holds the state machine (loading / unauthorized / error / form / pending / result)
• Route Map panel (data-hathor-culture-modeling-route-map, data-culture-route-count="5") — <h2> "Route Map" listing the 5 STUDIO_HATHOR_CULTURE_MODELING_ROUTE_MAP entries (/studio/hathor/culture-modeling + cultures / rituals / institutions / governance child paths). Each entry carries data-culture-route-map-entry and data-route-path.
• Quick-action lane (data-culture-quick-actions, data-culture-quick-action-count="3") — Character Modeling, Legal Systems Modeling, Back to Studio workspace index. Each link carries data-culture-quick-action.

States#

• Loading — <p data-culture-loading role="status" aria-live="polite"> "Loading culture analyser…" while the GET catalog request is in flight.
• Unauthorized (admin-scope 401/403) — data-culture-unauthorized role="alert" "Access restricted." with the BFF reason string.
• Error — data-culture-error role="alert" "Could not load the culture analyser." with the reason string for non-OK catalog responses, malformed catalog payloads, or network failures.
• Ready (form) — once catalog resolves: data-culture-enums role="status" aria-live="polite" count line (social structures · attitudes) plus data-culture-form data-culture-form-state="idle" aria-busy="false".
• Pending assessment — data-culture-form-state="pending", aria-busy="true", disabled textarea, disabled submit button, data-culture-submit-state="pending", and "Assessing…" button copy.
• Result — data-culture-result role="status" aria-live="polite" with data-culture-headline (cultureA ↔ cultureB · compatibility) and data-culture-metrics-grid (per-culture MetricsCards).
• Validation error — data-culture-assess-error role="alert" for invalid JSON, BFF 400 detail responses, malformed 200 result payloads, or transport failure.

Interactions#

Cultural Compatibility Lane#

• Cultures payload — <textarea data-culture-payload> (aria-label "cultures json"), JSON { cultureA:{…}, cultureB:{…} }; disabled while an assessment is pending.
• Submit — <button data-culture-submit> "Assess compatibility" / "Assessing…" → POST ASSESS_ENDPOINT; parses JSON client-side, sends { cultureA, cultureB }, renders a validated result on success, or reports validation / BFF / malformed-success / transport errors in place.

Route Map panel#

• Route entries — match STUDIO_HATHOR_CULTURE_MODELING_ROUTE_MAP (5 entries), with stable data-route-path ordering.

Quick-action lane#

• "Open Hathor Character Modeling workspace" (data-culture-quick-action="character-modeling") → /studio/hathor/character-modeling
• "Open Hathor Legal Systems Modeling workspace" (data-culture-quick-action="legal-systems-modeling") → /studio/hathor/legal-systems-modeling
• "Back to Studio workspace index" (data-culture-quick-action="studio-index") → /studio

Data & contracts#

• Reads: GET /v1/admin/hathor/culture-evolution-simulation (the CULTURE_ENDPOINT; note the endpoint slug differs from the route slug) — the catalog of social structures and attitudes.
• Writes: POST /v1/admin/hathor/culture-evolution-simulation/assess (ASSESS_ENDPOINT) with the parsed cultures payload.
• Realtime: none.
• Caching: client fetch on mount, cache: 'no-store', buildBffAuthHeaders(), AbortController on unmount for the catalog request.
• Auth/role check: admin-scoped, fail-closed on 401/403; route additionally gated signed-in + studio by the BFF proxy.
• Client parsing: GET catalog requires socialStructures: string[] and attitudes: string[]; POST success requires numeric compatibility, numeric socialMobility, numeric inequalityIndex, and string IDs/names/categories before rendering a result.

Cross-references#

• Parent: ../../studio-overview.md
• Shell: ../../../shell/04-auth-session.md
• Sibling routes: ./studio-hathor-character-modeling.md, ./studio-hathor-legal-systems-modeling.md, ./studio-hathor-culture-evolution-simulation.md
• Component sources:
  • apps/oshun/web/src/components/studio/StudioHathorCultureModelingWorkspace.tsx
  • apps/oshun/web/src/components/studio/StudioHathorCultureModelingRouteMap.ts

Automated coverage#

• apps/oshun/web/e2e/studio-hathor-culture-modeling.spec.ts covers: anonymous redirect, Hathor-admin shell entry, live culture catalog, default and edited culture-pair compatibility through the real BFF, browser bearer propagation, scoped axe, 44 px controls, route map, quick actions, client-only malformed JSON with zero POSTs, BFF detail surfacing, malformed success payload handling, transport failure, catalog loading/503/malformed states, non-admin fail-closed state, pending assessment lockout, mobile no-overflow containment, and direct BFF auth/schema gates.
• Focused component tests: StudioHathorCultureModelingWorkspace.test.tsx and StudioHathorCultureModelingWorkspace.integration.test.tsx.
• Focused BFF route test: apps/oshun/bff/src/__tests__/admin-hathor-culture-evolution-simulation-route.test.ts.

Open questions / known gaps#

• The GET/POST endpoints live under culture-evolution-simulation, not culture-modeling. Confirm this is intentional reuse of the culture-evolution admin backend rather than a wiring mistake.
• Hathor is unconfirmed-v1 per WALKTHROUGH/matrix/routes.csv; confirm whether the dedicated /studio/hathor/* admin lanes ship V1 or are internal-only. Confirmed in V1 via V1/TODOS.md §34 and the 2026-05-29 surface inventory.
• The route-map sub-routes are listed but their concrete page.tsx files are not present; confirm whether they remain route-map placeholders or need dedicated deep-link pages.
• Manual assistive-technology pass remains pending; automated scoped axe and keyboard/touch-target assertions pass for this route.