Studio Hathor · Lore Validation Causality

Purpose#

Admin lane console for the @hathor/validation CausalityValidator. The single validate lane submits a set of events with causal links and checks the causal graph for integrity — broken references, causes dated after their effects, and cycles (A→B→A) — plus opt-in orphan-effect and dangling-cause advisories. Admin-scoped and fail-closed.

Entry points#

• Direct URL / bookmark — /studio/hathor/lore-validation-causality; alternates.canonical is set.
• Quick-action from siblings — this page links to the Lore Validation Timeline lane.
• Studio overview — see ../../studio-overview.md.

Layout regions#

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

• Workspace (StudioHathorLoreValidationCausalityWorkspace, data-hathor-lore-validation-causality-workspace):
  • <h1> WorkspaceHeading — "Hathor Lore Validation Causality Workspace"
  • Summary <p data-hathor-lore-validation-causality-summary>
  • The catalog state (data-hathor-lvc-catalog), then the events form (with advisory toggles), pending submit state, validation errors, and result.
• Route Map panel (<section data-hathor-lore-validation-causality-route-map>, <h2>Route Map</h2>): 5 entries from STUDIO_HATHOR_LORE_VALIDATION_CAUSALITY_ROUTE_MAP (path + purpose).
• Quick-action lane (data-hathor-lvc-quick-actions, data-hathor-lvc-quick-action-count="2"): Lore Validation Timeline (data-hathor-lvc-quick-action="lore-validation-timeline") and Back to Studio workspace index (data-hathor-lvc-quick-action="studio-index").

States#

• Loading — <p data-hathor-lvc-loading> "Loading causality validator…".
• Unauthorized — data-hathor-lvc-unauthorized on 401/403 (admin-scope).
• Error — data-hathor-lvc-error on a non-OK catalog response or network failure.
• Ready (form) — data-hathor-lvc-validate-form with data-hathor-lvc-form-state="idle", the events textarea, and the three advisory checkboxes.
• Pending submit — data-hathor-lvc-form-state="validating" and data-hathor-lvc-submit-state="validating"; submit is disabled with aria-disabled="true" and aria-busy="true" until the BFF response returns.
• Result — data-hathor-lvc-result with data-hathor-lvc-valid, data-hathor-lvc-counts (links / errors / warnings / cycles / orphan / dangling), and data-hathor-lvc-issues rows (or data-hathor-lvc-clean).
• Validation error — data-hathor-lvc-validate-error for malformed JSON, an empty array, or a failed POST.

Interactions#

• data-hathor-lvc-events (textarea, aria-label="events json") — edit the events JSON array ({ id, name, year, causes?, effects?:[{ eventId, type?, strength? }] }).
• data-hathor-lvc-detect-cycles (checkbox) — toggle cycle detection.
• data-hathor-lvc-warn-orphans (checkbox) — toggle orphan-effect advisory.
• data-hathor-lvc-warn-dangling (checkbox) — toggle dangling-cause advisory.
• data-hathor-lvc-validate-submit ("Validate causality") — parses the JSON and POSTs { events, detectCycles, warnOrphanEffects, warnDanglingCauses }; on 200 with a valid result renders the verdict.
• Route Map entries — verify against STUDIO_HATHOR_LORE_VALIDATION_CAUSALITY_ROUTE_MAP (5 entries).
• Quick-action links — Lore Validation Timeline (/studio/hathor/lore-validation-timeline), Back to Studio (/studio).

Data & contracts#

• Reads: GET /v1/admin/hathor/lore-validation-causality (catalog: issueCodes, causalityTypes, strengths), rendered as data-hathor-lvc-catalog.
• Writes: POST /v1/admin/hathor/lore-validation-causality/validate with the events + advisory flags. The happy path returns { ok: true, result }; invalid events return BFF 400 reason strings such as invalid_event, which the lane surfaces in data-hathor-lvc-validate-error.
• Realtime: none.
• Caching: client fetch on mount, cache: 'no-store', buildBffAuthHeaders(), AbortController on unmount.
• Auth: admin-scoped, fail-closed (401/403 → unauthorized); route is behind the signed-in + studio proxy gate.

Cross-references#

• Parent: ../../studio-overview.md
• Component sources:
  • apps/oshun/web/src/components/studio/StudioHathorLoreValidationCausalityWorkspace.tsx
  • apps/oshun/web/src/components/studio/StudioHathorLoreValidationCausalityRouteMap.ts
• Siblings: ./studio-hathor-lore-validation-timeline.md, ./studio-hathor-lore-validation-contradictions.md, ./studio-hathor-lore-validation-taxonomy.md, ./studio-hathor-unified-validation-dashboard.md

E2E coverage#

• apps/oshun/web/e2e/studio-hathor-lore-validation-causality.spec.ts — signed-in admin route; real Hathor causality-validation BFF catalog and validate calls; seeded CAUSALITY_CYCLE_DETECTED; opt-in CAUSALITY_ORPHAN_EFFECT / CAUSALITY_DANGLING_CAUSE; malformed JSON and empty-array zero-POST branches; live BFF invalid_event 400 detail; catalog loading/error; pending submit lockout; non-admin fail-closed state; anonymous redirect; route-map and quick-action anchors; automated 44px checks for the main editable controls and quick actions; shared axe gate.
• Supporting route contract coverage: apps/oshun/bff/src/__tests__/admin-hathor-lore-validation-causality-route.test.ts covers auth/scope, issue-code/type/strength catalog, chain break, temporal violation, cycle detection, clean chain advisories, and BFF 400 payload validation.

Open questions / known gaps#

• Hathor is confirmed in V1 per WALKTHROUGH/matrix/routes.csv and WALKTHROUGH/matrix/coverage.md (product-owner confirmation recorded 2026-05-29 for Bellona / Hathor / Neith).
• Manual screen-reader pass remains for the live browser surface; automated axe and touch-target coverage now pass for the route-level controls.