# Sequential financial dashboard releases and provider dry-runs

Use this reference for an ordered multi-PR financial-dashboard release where every PR must independently pass review, CI, exact-SHA deployment, and production-safe UAT.

## Ordered release contract

1. Freeze the starting SHA. Create each branch/worktree from the verified merge SHA of the preceding PR.
2. Keep each PR vertically complete: implementation, regressions, responsive/API UAT, independent review, CI, merge, exact-SHA deployment, and production smoke.
3. Treat all reviewer P0/P1/P2 findings as blockers. A timed-out reviewer is not a PASS: inspect its transcript, consume reproduced findings, fix them, then dispatch a narrow verdict-only closure review.
4. If files change after a review/full suite, invalidate that evidence and rerun the affected gates; before publication obtain an exact-tree P0/P1/P2 verdict.
5. Commit only after gates close. Verify CI by exact head SHA, merge normally, and prove the merge tree equals the reviewed feature tree.
6. Before deployment, create a current online SQLite backup and exercise an isolated restore/integrity/FK/schema check. Deploy and rebuild only the exact merge SHA.
7. Verify runtime SHA, services, HTTP, DB integrity, FK state, schema version, and prescribed read-only/preview-only production UAT. Stop temporary servers and prove their ports are free.

## Dedicated provider dry-run under a write guard

A provider-backed dry-run is database-read-only but can consume quota or incur cost. Never exempt the normal mutation endpoint based only on a client-supplied `dry_run` body field.

Preferred design:

- Provide a dedicated dry-run POST route.
- Add only that exact route to the read-only POST allowlist.
- Force `dry_run=True` and full-scope flags server-side, ignoring contradictory body values.
- In write-disabled UAT, allow it only from TestClient/loopback; reject remote callers to prevent provider-quota abuse.
- Keep the actual apply route under the ordinary local-write policy.
- Return target date, accepted provider-date range, eligible count, provider-call count, accepted/would-update count, truncation, errors, and `persistence_performed`.
- Prove no-write behavior with synthetic content/count assertions and a SHA-256 before/after comparison on an isolated production copy. Repeat the hash proof in production dry-run UAT and never invoke apply during that UAT.

## UI semantics and concurrency

- Label the local view reload explicitly and state that it does not call providers.
- Require a completed dry-run before exposing the full apply action; bind apply to the preview target date.
- Serialize batch refresh, single-item refresh, chart provider load, and conflicting view reloads. Disable every conflicting control and guard handlers against programmatic double invocation.
- Invalidate a preview when another mutation changes relevant quote state.
- Separate mutation success from subsequent view/detail reload success. If persistence succeeded but reload failed, report “saved; view reload failed,” not “mutation failed,” so users do not retry a successful write.
- Display target and returned provider dates distinctly; a previous portfolio valuation date must not silently become the next refresh target.

## Review probes

- Verify cached instruments are still provider-called during a requested full refresh (`only_missing=False`).
- Verify limit truncation is explicit and blocks UI confirmation when the run is not full-scope.
- Verify dry-run performs no quote, chart-point, valuation, or audit writes.
- Verify ordinary apply remains blocked in disabled mode even when its body says `dry_run=true`.
- Verify a non-loopback client cannot call the provider dry-run route.
- Verify provider/UI operations cannot overlap and that successful persistence is not relabeled as failure by a later GET error.

## CI and evidence

If GitHub GraphQL check access is restricted, use the authenticated Actions REST endpoint filtered by exact `head_sha`. Require at least one discovered run and require every run to be `completed/success` before merge.

Keep committed and user-facing evidence aggregate-only. Do not include account IDs, instruments, prices, raw provider payloads, finance screenshots, credentials, or private runtime paths unless the path itself is required for owner recovery.