Studio Hathor · Simulation State Persistence

Purpose#

Admin lane console for the Hathor simulation persistence primitives. Enter a simulation state payload and read back its canonical cache keys (state:<id>, world:<id>:*, domain:<name>:* from @hathor/simulation), the serialized form, whether the @hathor/domain-models serialize→deserialize round-trip is stable, and which date fields hydrate back into Date instances. Admin-scoped and fail-closed.

Entry points#

• Direct URL / bookmark — /studio/hathor/simulation-state-persistence; alternates.canonical is set.
• Breadcrumb / quick-action — Studio › Hathor › Simulation › Simulation State Persistence (sibling lane); this page links back to the Simulation aggregator and to Simulation Physics.
• Studio overview — see ../../studio-overview.md.

Layout regions#

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

• Breadcrumb panel (<section data-hathor-simulation-state-persistence-breadcrumbs>): Studio → Hathor → Simulation → Simulation State Persistence (sibling lane).
• Workspace (StudioHathorSimulationStatePersistenceWorkspace, data-hathor-simulation-state-persistence-workspace):
  • <h1> WorkspaceHeading — "Hathor Simulation State Persistence Workspace"
  • Summary <p data-hathor-simulation-state-persistence-summary>
  • Catalog state, then the persistence form + result.
• IA-contract panel (<section data-hathor-simulation-state-persistence-route-map>, <h2>Hathor Simulation cluster — IA contract</h2>): renders STUDIO_HATHOR_SIMULATION_STATE_PERSISTENCE_ROUTE_MAP (7 entries) grouped by role — one parent-aggregator, one self, and five peer-lane entries.
• Quick-action lane (className="quickAction" Links): Back to Hathor Simulation aggregator, Simulation Physics, Back to Studio workspace index.

States#

• Loading — <p data-hathor-sp-loading> "Loading persistence engine…".
• Unauthorized — data-hathor-sp-unauthorized on 401/403 (admin-scope).
• Error — data-hathor-sp-error on a non-OK catalog response or network failure.
• Ready (form) — data-hathor-sp-form with state id / world id / domain inputs, the payload textarea, and the date-fields input.
• Result — data-hathor-sp-result with data-hathor-sp-key-state / -key-world / -key-domain, data-hathor-sp-roundtrip, and data-hathor-sp-hydrated.
• Validation error — data-hathor-sp-persist-error for missing ids, malformed JSON, or a failed POST.

Interactions#

• data-hathor-sp-state-id / -world-id / -domain (inputs) — the cache key components.
• data-hathor-sp-payload (textarea, aria-label="payload json") — the state payload.
• data-hathor-sp-date-fields (input, aria-label="date fields") — comma-separated date field names.
• data-hathor-sp-submit ("Inspect persistence") — validates ids and JSON then POSTs { stateId, worldId, domain, payload, dateFields }; on 200 with a valid result renders the cache keys + round-trip read-out.
• IA-contract entries — verify against STUDIO_HATHOR_SIMULATION_STATE_PERSISTENCE_ROUTE_MAP (parent + self + 5 peers).
• Quick-action links — Hathor Simulation (/studio/hathor/simulation), Simulation Physics (/studio/hathor/simulation-physics), Back to Studio (/studio).

Data & contracts#

• Reads: GET /v1/admin/hathor/simulation-state-persistence (catalog: keySchemes, defaultDateFields).
• Writes: POST /v1/admin/hathor/simulation-state-persistence/persist with the state descriptor + payload.
• 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/StudioHathorSimulationStatePersistenceWorkspace.tsx
  • apps/oshun/web/src/components/studio/StudioHathorSimulationStatePersistenceRouteMap.ts (role-tagged IA contract)
• Aggregators that embed this lane: ./studio-hathor-database.md
• Siblings: ./studio-hathor-simulation.md (parent aggregator), ./studio-hathor-simulation-physics.md, ./studio-hathor-simulation-worker.md

Open questions / known gaps#

• Hathor is unconfirmed-v1 per WALKTHROUGH/matrix/routes.csv; confirm whether the dedicated /studio/hathor/* admin lanes ship V1 or are internal-only.