---
path: /studio/hathor/faction-modeling
surface: studio
domain: hathor
auth: signed-in + studio entitlement
source: apps/oshun/web/src/app/studio/hathor/faction-modeling/page.tsx
status: walked
last_walked:
  '2026-05-29 automated runtime walk (Playwright headless) — render, /v1 data
  (2xx), console/page-errors, expected content, screenshot verified; live
  screen-reader, touch, offline, and telemetry-delivery checks pending a manual
  AT pass. Evidence: WALKTHROUGH/results/runtime-sweep-2026-05-29.md; body
  re-derived 2026-06-03 from current source (lane-console architecture)'
---

# Studio Hathor · Faction Modeling

## Purpose

Admin lane console that scores a board of factions for power — running the real
faction power-scoring algorithm over government type, leadership, resources,
member loyalties, controlled territories, and relationships. The operator submits
a JSON faction board and the lane returns per-faction power rows.

## Entry points

- **Quick-action link from `/studio/hathor/geography-modeling`** (verify against
  that page's source)
- **Direct URL / bookmark** — yes; `alternates.canonical` set to
  `/studio/hathor/faction-modeling`
- **Studio overview** — see
  [`../../studio-overview.md`](../../studio-overview.md)

## Layout regions

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

- **Workspace** `<StudioHathorFactionModelingWorkspace />`
  (`data-hathor-faction-modeling-workspace`):
  - `WorkspaceHeading` `<h1>` — "Hathor Faction Modeling Workspace"
  - Summary `<p data-hathor-faction-modeling-summary>`
  - **Faction Power Scoring Lane** — `<h2 data-fac-lane-heading>`; holds the
    loading / unauthorized / error / form / result states
- **Route Map panel** `data-hathor-faction-modeling-route-map` — `<h2>` "Route
  Map" listing the 5 `STUDIO_HATHOR_FACTION_MODELING_ROUTE_MAP` entries
  (factions / hierarchies / relations / governance child paths)
- **Quick-action lane** — two `Link.quickAction` anchors: Geography Modeling,
  Back to Studio workspace index

## States

- [ ] **Loading** — `data-fac-loading` while the GET catalog request is in flight
- [ ] **Unauthorized (admin-scope 401/403)** — `data-fac-unauthorized`
- [ ] **Error** — `data-fac-error`
- [ ] **Ready (form)** — `data-fac-types` enum hint + faction-board textarea +
      submit
- [ ] **Result** — `data-fac-result` with `data-fac-factions` (per-faction
      `data-fac-faction-row` carrying `data-faction-id` / `data-power`)
- [ ] **Validation error** — `data-fac-score-error`

## Interactions

### Faction Power Scoring Lane

- [ ] **Faction board** — `<textarea data-fac-payload>`, JSON
      `{ factions:[{ factionId, name, type, government, status, hasLeader,
      resources, memberLoyalties, controlledTerritories, relationships }] }`
- [ ] **Submit** — `<button data-fac-submit>` "Score factions" → POST
      `SCORE_ENDPOINT`

### Route Map panel

- [ ] **Route entries** — verify match with
      `STUDIO_HATHOR_FACTION_MODELING_ROUTE_MAP` (5 entries)

### Quick-action lane

- [ ] **"Open Hathor Geography Modeling workspace"** → `/studio/hathor/geography-modeling`
- [ ] **"Back to Studio workspace index"** → `/studio`

## Data & contracts

- **Reads**: `GET /v1/admin/hathor/workbench-factions` (`FAC_ENDPOINT`; note the
  endpoint slug differs from the route slug — it reuses the workbench-factions
  admin backend) — the faction-type catalog
- **Writes**: `POST /v1/admin/hathor/workbench-factions/score` (`SCORE_ENDPOINT`)
  with the faction board
- **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`](../../studio-overview.md)
- Shell:
  [`../../../shell/04-auth-session.md`](../../../shell/04-auth-session.md)
- Sibling routes:
  [`./studio-hathor-geography-modeling.md`](./studio-hathor-geography-modeling.md),
  [`./studio-hathor-workbench-factions.md`](./studio-hathor-workbench-factions.md)
- Component sources:
  - `apps/oshun/web/src/components/studio/StudioHathorFactionModelingWorkspace.tsx`
  - `apps/oshun/web/src/components/studio/StudioHathorFactionModelingRouteMap.ts`

## Open questions / known gaps

- [ ] The GET/POST endpoints live under `workbench-factions`, not
      `faction-modeling`. Confirm this shared backend is intentional and that the
      two routes are meant to expose the same scoring engine.
- [ ] Hathor is `unconfirmed-v1` per `WALKTHROUGH/matrix/routes.csv`. Confirm
      whether the dedicated `/studio/hathor/` lane consoles ship at V1 or are
      internal-only.