Build Stateful Repair CLI on Top of Synapse

[Kubuxu]

Summary

Build the durable operator tooling needed to execute manual repairs safely and resume after interruption.

Why

Repair is long-running and piece-based. Stateless scripts are not good enough if they crash mid-operation.

Scope

• accept a dataset or provider as input
• use the repair inventory to determine available repair sources and destination actions
• support creating a new destination dataset or reusing an existing operator-controlled dataset
• execute repair by copying or uploading pieces into the destination dataset using Synapse
• persist progress and retry state
• resume cleanly after crash or operator restart
• produce a verification summary

Non-Goals

• generic orchestration platform
• unattended auto-remediation
• internal GUI

Done Criteria

• CLI supports dataset-level repair execution
• CLI supports provider-driven execution by expanding provider scope into dataset-by-dataset repair work
• CLI can create or reuse the destination dataset used for repaired pieces
• piece-level progress is persisted durably
• CLI can resume safely after interruption without losing track of work
• retries and restarts do not duplicate or lose track of work
• operator gets a final report of success/failure by piece

Subtasks

• define repair state model
• define CLI commands and operator workflow
• implement provider-to-dataset repair expansion flow
• implement destination dataset handling
• integrate Synapse upload / transfer operations
• implement persistence and resume behavior
• implement verification output

[Kubuxu]

Estimate: 5 days.

Assumption: narrow operator CLI scope: simple durable local state, resumable piece-level execution, Synapse happy path first, retries/restarts that do not lose track of work, and a practical verification summary.

[BigLep]

@Kubuxu : you don't need to change it, but on the surface I'm surprised this item is this big given it's target audience is operators/maintainers rather than end users. I would have thought we could be more scrappy here.

[Kubuxu]

I think this might be reading heavier than intended.

The main thing I was optimising for is resumability, since the tool will operate over thousands of pieces and will inevitably hit failures.

That said, I’m aiming for a simple operator-facing tool:

• lightweight persistence (e.g., JSON log)
• no strict guarantees beyond safe resume
• operators still in the loop for edge cases

The subtask breakdown is more about structuring the work than implying full design artefacts.

The estimate is a bit higher, mainly due to unknowns, since some earlier pieces aren’t in place yet.

[hugomrdias]

@BigLep i can help with this one

[Kubuxu]

@hugomrdias is taking this on