Skip to main content
← Back to list
01Issue
BugOpenSwamp CLIPublic
AssigneesNone

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.

02Bog Flow
◉OPEN○TRIAGED○IN PROGRESS○SHIPPED

Open

10/27/2026, 6:51:55 PM

No activity in this phase yet.

03Sludge Pulse
Editable. Press Enter to edit.

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.