---
path: /studio/hathor/simulation-state-persistence
surface: studio
domain: hathor
auth: signed-in + studio entitlement
source: apps/oshun/web/src/app/studio/hathor/simulation-state-persistence/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 · 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`](../../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`](../../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`](./studio-hathor-database.md)
- Siblings:
  [`./studio-hathor-simulation.md`](./studio-hathor-simulation.md) (parent
  aggregator),
  [`./studio-hathor-simulation-physics.md`](./studio-hathor-simulation-physics.md),
  [`./studio-hathor-simulation-worker.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.