Relationships
#4040 Docs: doctor datastores --repair --json describes a repairReport shape the CLI never produced
Opened by stack72 · 10/27/2026
What is wrong
content/manual/reference/doctor.md, section "doctor datastores" > "JSON shape" > "Repair (--json --repair)", says the repair adds a repairReport object with mode, steps (step, name, status) and recoveredRunCount. swamp has never printed that shape for doctor datastores.
What the CLI prints
Since swamp-club#4011 (swamp PR #3423), a format 2 datastore's repair under --json prints one object keyed by repair stage. Each value is that stage's status object, or null when the stage did not run (no namespace, no contamination repair for the datastore, a namespace-collision skip, or a stage that failed; the exit code and the stderr error tell these apart):
{
"unmigrated": null,
"catalog": { "status": "catalog_not_needed" },
"duplicateLatest": { "status": "duplicate_latest_not_needed" },
"contamination": null
}Stage statuses:
- unmigrated: unmigrated_preview (namespace, directories), unmigrated_completed (namespace, result), unmigrated_not_needed
- catalog: catalog_preview (completeness, foreignRowsNotice), catalog_completed (result, foreignRowsNotice), catalog_not_needed
- duplicateLatest: duplicate_latest_preview (duplicateCount), duplicate_latest_completed (result), duplicate_latest_not_needed
- contamination: preview (namespace, contamination), completed (namespace, result, steps), not_needed
The v3 format-marker and pre-v3-records repairs are unchanged: each still prints a single status object, as the "Format marker repair" section already describes.
Suggested change
Replace the repairReport example in that section with the keyed shape above and the stage status list.
Open
No activity in this phase yet.
system commented 10/27/2026, 6:51:55 PM
Classified automatically when this issue was filed.
- Type: Bug
If you feel this classification is incorrect, add a ripple to tell us so.
Sign in to post a ripple.