# Harbor state recovery

Harbor keeps the existing data directory and `state.json` path. The current persisted format is `schemaVersion: 5`: schema v2 introduced local route rules, v3 added rule enabled state, v4 added stable server IDs, and v5 embeds the canonical `profiles[]` collection with desired/applied profile identity.

## Atomic writes

Persistent files are written to a unique temporary file in the same directory, flushed with `fsync`, closed and atomically renamed over the target. A failure before rename leaves the previous target untouched and removes the temporary file.

Profile/server switching prepares candidate config and runtime before the final state publication. If any later step fails, Harbor restores the previous config, runtime and canonical state.

## Migration to profiles

On startup, a legacy state is normalized before the process starts. Harbor creates one profile named `Основной`, moves the provider URL/config and metadata into it, and preserves unambiguous desired/applied server identity. A legacy state explicitly marked stopped clears stale applied residue.

Before replacing state Harbor saves the original beside it:

```text
state.json.backup-v4-2026-08-11T12-00-00-000Z
```

After a valid profile has been committed, the raw legacy cache is saved and removed as a second owner:

```text
subscription-cache.json.backup-v1-2026-08-11T12-00-00-000Z
```

An invalid legacy provider config is backed up but not started. Harbor removes stale generated config and returns to a stopped first-run state.

## Corrupt JSON

If `state.json` cannot be parsed, Harbor renames the exact damaged bytes to:

```text
state.json.corrupt-2026-08-11T12-00-00-000Z
```

It then creates a valid empty current-schema state and reports storage recovery. A corrupt legacy subscription cache is preserved with the same suffix and is never used to start stale config.

## Manual recovery and downgrade

Perform recovery while Harbor is stopped:

1. Copy the whole data directory.
2. Inspect the intended backup with `jq . <backup-file>`.
3. Restore only matching state/cache backups to their original filenames.
4. Start Harbor and verify `GET /api/state` before applying a profile.

A pre-v5 binary cannot interpret canonical profiles. Downgrade therefore requires both pre-migration backups; deploying old code alone is not a safe rollback.