Studio Hathor · Lore Validation Timeline

Purpose#

Admin lane console for the @hathor/validation TimelineValidator. The single validate lane submits a set of historical events and checks temporal integrity — events occurring before a declared cause (or after a declared effect), durations that end before they start, and (opt-in) large gaps between consecutive events. Admin-scoped and fail-closed.

Entry points#

• Direct URL / bookmark — /studio/hathor/lore-validation-timeline; alternates.canonical is set.
• Quick-action from siblings — the Lore Validation Causality lane links here; this page links out to NPC Platform Integrations.
• Studio overview — see ../../studio-overview.md.

Layout regions#

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

• Workspace (StudioHathorLoreValidationTimelineWorkspace, data-hathor-lore-validation-timeline-workspace):
  • <h1> WorkspaceHeading — "Hathor Lore Validation Timeline Workspace"
  • Summary <p data-hathor-lore-validation-timeline-summary>
  • The catalog state (data-hathor-lvt-catalog), then the events form (with gap toggle + threshold), pending submit state, validation errors, and result.
• Route Map panel (<section data-hathor-lore-validation-timeline-route-map>, <h2>Route Map</h2>): 5 entries from STUDIO_HATHOR_LORE_VALIDATION_TIMELINE_ROUTE_MAP (path + purpose).
• Quick-action lane (data-hathor-lvt-quick-actions, data-hathor-lvt-quick-action-count="2"): NPC Platform Integrations (data-hathor-lvt-quick-action="npc-platform-integrations") and Back to Studio workspace index (data-hathor-lvt-quick-action="studio-index").

States#

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

Interactions#

• data-hathor-lvt-events (textarea, aria-label="events json") — edit the events JSON array ({ id, name, year, causes?, effects?, duration? }).
• data-hathor-lvt-check-gaps (checkbox) — toggle gap detection.
• data-hathor-lvt-gap-threshold (input, aria-label="gap threshold") — the gap threshold in years (sent only when gap detection is on).
• data-hathor-lvt-validate-submit ("Validate timeline") — parses the JSON and POSTs { events, checkGaps, gapThresholdYears? }; on 200 with a valid result renders the verdict.
• Route Map entries — verify against STUDIO_HATHOR_LORE_VALIDATION_TIMELINE_ROUTE_MAP (5 entries).
• Quick-action links — NPC Platform Integrations (/studio/hathor/npc-platform-integrations), Back to Studio (/studio).

Data & contracts#

• Reads: GET /v1/admin/hathor/lore-validation-timeline (catalog: issueCodes, defaultGapThresholdYears), rendered as data-hathor-lvt-catalog.
• Writes: POST /v1/admin/hathor/lore-validation-timeline/validate with the events + gap 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-lvt-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/StudioHathorLoreValidationTimelineWorkspace.tsx
  • apps/oshun/web/src/components/studio/StudioHathorLoreValidationTimelineRouteMap.ts
• Siblings: ./studio-hathor-lore-validation-causality.md, ./studio-hathor-npc-platform-integrations.md, ./studio-hathor-unified-validation-dashboard.md (runs Timeline + Causality + Taxonomy over one payload)

E2E coverage#

• apps/oshun/web/e2e/studio-hathor-lore-validation-timeline.spec.ts — signed-in admin route; real Hathor timeline-validation BFF catalog and validate calls; seeded TIMELINE_ORDER_VIOLATION; opt-in TIMELINE_GAP_DETECTED; malformed JSON / empty array / invalid threshold 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-timeline-route.test.ts covers auth/scope, issue-code catalog, clean order, order violation, invalid duration, gap detection, 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.