# Bellona Format Registry Troubleshooting

## Scope

This runbook supports the Bellona Format Registry workspace:

- Route map:
  `docs/releases/v1/specs/studio-bellona-format-registry-route-map.md`
- Workspace route: `/studio/bellona/format-registry`

## policy-denials

Symptoms:

- Create/edit wizard, reconnect, import/export, or parity controls are disabled.
- Policy panel shows `role-tier mismatch` or `Justification: required`.

Checks:

1. Confirm role and tier alignment in policy context.
2. Confirm justification text length is at least 12 characters for non-baseline
   tiers.
3. Confirm approval actions are only attempted at restricted tier.

Recovery:

1. Set role/tier to an allowed combination.
2. Provide explicit rationale text in policy justification.
3. Re-run blocked action and verify policy denial banner clears.

## stream-reconnect-instability

Symptoms:

- Stream state remains `lagging` or `offline` after reconnect attempts.
- Reconnect counts continue rising without stabilizing latency.

Checks:

1. Verify stream is not paused.
2. Validate selected records are in scope and reconnect is not already
   in-flight.
3. Inspect observability panel for p95 latency and failure-rate spikes.

Recovery:

1. Run row reconnect for targeted records.
2. Run bulk reconnect for selected cohorts after scope narrowing.
3. If instability persists, pause stream updates, capture audit + telemetry
   evidence, and escalate.

## api-parity-drifts

Symptoms:

- API parity report is `fail`.
- Report lists missing local IDs, missing baseline IDs, or field mismatches.

Checks:

1. Export current payload for forensic snapshot.
2. Inspect parity mismatch lines to identify
   direction/status/owner/version/handler drift.
3. Confirm imported payload provenance and schema contract.

Recovery:

1. Import a known-good exported payload from a healthy baseline.
2. Re-run API parity validation and confirm `API parity: pass`.
3. Capture change-history entry and telemetry trace before release decisions.
