[dawsontoth]

⊙ Problem

Harper 5.2+ can take and manage database backups. Studio has no screen for them. Fabric customers must type operations into the Operations console.

💡 Solution

• A Backups tab under Config, for super users on Harper 5.2 or later.
• Pick a database, then take a backup and follow its job, list backups with id, time, size and attachments, verify one, delete one, or keep only the newest N. A purge first names what it deletes.
• Each cluster node gets its own card. Every request goes to that node through /HDBInstance/<id>/operation. The cluster's own address reaches whichever node runs first.
• Harper's own message shows when it refuses a command.
• The page says backups live on the node's disk, are lost with the node, and can't be restored from Studio yet.

🤔 Keep newest N starts at 1

Harper accepts keep_count: 0, which deletes every backup. The dialog asks for at least 1, so clearing a database's backups takes one Delete per row. Say if 0 should be allowed.

🤔 Leaving the page stops following a job

Studio follows a job only while the page is open. The backup still finishes and shows in the list later, but its result message is lost. Keeping followed jobs per node across pages is possible; say if it's wanted.

⚖️ Alternatives

• One list through the cluster's address — it reaches whichever node runs first, so backups would seem to come and go.
• Backups only on each instance's page — simpler, but the cluster page is where admins look, and Backups: let customers take and manage database backups in Studio #2008 asks to show which node holds each backup.

Decisions the review raised

• version-gate-waits-for-both: on a cluster either registration_info or the cluster record can show the page, but it says backups are unsupported only once both are in, so neither can flash a verdict the other reverses.
• verify-lock-scope: Verify waits behind every other write on its node and database, matching Harper's one-at-a-time lock. Two backups can't be verified at once from Studio.
• delete-refuses-without-timestamp: delete refuses when it can't tell two backups apart. Harper always sends timestamp, so only a malformed answer hits this.

🔧 Changes

• backups.ts — the five operations, taken as a background job, behind the 5.2.0 gate (no 5.2.0 prerelease has them). The job poll is pinned to the node running the job, since hdb_job doesn't replicate, and never retries a 403. Verify and delete re-read the list and refuse when the id names another backup, matching timestamp, size and file count; Harper offers no other identity and no precondition, so a narrow window remains. Purge reports Harper's own count, and the confirmation says what it removes. An accepted request with no job id is an unknown outcome.
• backups/index.tsx — the super-user gate, a cluster shown once any member runs 5.2 and no verdict from a member list it couldn't read, the database picker and the on-page warnings. Each member gets a client pinned to it through Fabric; without cluster update permission, or on a self-hosted cluster, the page says why instead.
• BackupNodeSection.tsx — one card per node. Every write is held while one runs, a dialog is bound to its database, a verify result matches on id and timestamp, a refusal re-reads the list, and a purge toast never invents a count.
• BackupJobLine.tsx — job progress. A job missing for 20 s or refused with a 403 ends as unknown and frees the node.
• BackupDialogs.tsx — the take, verify and keep-newest confirmations.
• backupNodes.ts — which members to list: removed ones are skipped, unreachable or old ones say why, sorted by name.
• config/index.tsx, routes.ts — the version rule and nav entry, the route and where it mounts.
• queryClient.ts — the unknown-outcome wording for an accepted request with no job.
• backups/DESIGN.md, DESIGN.md — why requests are pinned to a node and what size and id mean; the root index entry and unknown-outcome list.

✅ Verification

• Live, against a local Harper 5.3.6 in Local Studio mode: took, verified, purged and deleted backups through the page. Harper's 404 for a backup deleted elsewhere showed as a toast, and the stale row went away.
• That run found Harper reusing ids once every backup is gone. A verify result now matches on id and timestamp, and delete and verify check the backup before sending.
• 53 new tests. index.test.tsx drives the page against fake per-node clients with a real QueryClient: jobs followed on their node, a delete refused on id reuse, a partly upgraded cluster. backupNodes.test.ts and backups.test.ts cover member selection and request shapes. Removing any of the node pinning, the busy hold, the list refresh, the identity checks, the any-member rule, the 403 handling, the missing-job recheck or the dialog binding turns a test red.
• Full gate: vitest (650 files, 7,131 tests), tsc -b, oxlint, dprint. The Fabric per-node route needs Fabric and wasn't run live; it is the client InstanceStatusCell already uses.

Closes #2008

_{🤖 Generated by Anthropic Claude (Claude Code); posted via @dawsontoth.}

Related PRs: #2031 overlaps (Config nav entries and route list), #2065 overlaps (Config nav entries and route list)
Complexity: medium

Deferred findings

• 2e5a2c17d141883c nit maintainability — src/integrations/api/instance/backups/backups.test.ts — relative imports lack the .ts extension — NOT FILED

_{Review-Coverage: authored=claude; ran=cursor-composer,gemini,codex,cursor-grok; late=cursor-grok:adjudicated; adjudicated=domain; declined=muse; rounds=6; full=2 @ 293f578}

_{Review-Attention: study ~11m (decisions: do-less-alternative, version-gate-waits-for-both, verify-lock-scope, delete-refuses-without-timestamp) @ 293f578}

[github-actions]

Coverage Report

Status	Category	Percentage	Covered / Total
🔵	Lines	83.56%	18846 / 22553
🔵	Statements	83.42%	19961 / 23926
🔵	Functions	79.12%	5124 / 6476
🔵	Branches	78.88%	15663 / 19855

File Coverage

File	Stmts	Branches	Functions	Lines	Uncovered Lines
Changed Files
src/features/instance/config/index.tsx	14.28%	0%	0%	14.28%	43-284
src/features/instance/config/routes.ts	67.21%	100%	51.21%	67.21%	25, 32, 40, 47, 53, 60, 66, 73, 80, 87, 93, 101, 108, 116, 123, 131, 137, 144, 151, 157
src/features/instance/config/backups/BackupDialogs.tsx	87.5%	73.17%	80%	87.5%	50, 84, 119, 145
src/features/instance/config/backups/BackupJobLine.tsx	95.23%	81.13%	100%	95.12%	90, 115
src/features/instance/config/backups/BackupNodeSection.tsx	92.39%	88.04%	88.63%	94.18%	70, 75, 160, 244, 304
src/features/instance/config/backups/backupNodes.ts	100%	85.18%	100%	100%
src/features/instance/config/backups/index.tsx	91.89%	86.11%	83.33%	91.66%	99-102, 134, 138, 153, 155
src/integrations/api/instance/backups/backups.ts	100%	100%	100%	100%
src/react-query/queryClient.ts	98.57%	100%	88.88%	98.55%	136

Generated in workflow #2550 for commit 293f578 by the Vitest Coverage Report Action

[gemini-code-assist]

Code Review

This pull request introduces a comprehensive database backup management feature for Harper databases (version 5.2.0+). It adds a new 'Backups' section under the instance configuration, allowing users to take, verify, delete, and purge backups on a per-node basis. The implementation includes React components for dialogs and job tracking, API integrations, routing updates, detailed design documentation, and extensive unit and integration tests. I have no feedback to provide as there are no review comments to assess.

[kriszyp]

_{🤖 Reviewed with Muse Wonder 1.0 · adjudicated by Codex}