feat(doctor): read-only five-layer health surface (spec + first implementation) - #112
Merged
Conversation
…mentation) sideshow doctor reports on the state sideshow itself has written: store, receipts, sync manifest, and repo-bindings ledger. Layers per orc charter F24: (1) native integrity, (3) cwd discoverability warn-only, (4) fleet drift, (5) known defects. Layer 2 is excluded by decision and the text output explains the gap in place. Result model: four statuses (ok, warn, fail, unavailable) crossed with a structural/advisory class. Only structural failures move the exit code (2); --strict promotes structural warns; advisory and unavailable never gate, under any flag. That is the orc diagnostic-not-gate rule expressed as code, and the exit table has a test row per branch. Absent inputs report unavailable with the ticket that supplies them (no lockfile: aae-orc-333y; no defects feed: aae-orc-ztg5 and aae-orc-10vq; no retained release manifests: aae-orc-wk92). Silence never reads as cleanliness: zero checksummed receipts is unavailable with both known under-coverage causes named, not clean. Layer 1 checks: registry parse, registry/current-symlink/version-dir coherence, installer-output shape (closes the aae-orc-xbkl surface), store freeze bits (advisory, benign causes named), per-file content census against the pack's own files-manifest.csv, sync-manifest presence + version currency (custom-source entries exempt), receipted claude_md marker pairing and rules managed-by lines, receipted symlink resolution. Plugin-class seam ships ledger-row-coherence so the aae-orc-d3nq.9 slot is proven by use, not merely declared. Layer 3 wraps coexist-check, the foreign census grades, and the factory guard, clamped to advisory warn-or-below by the runner. Layer 4 re-hashes checksummed receipts against disk (the sideshow#92 signal, which needs no lockfile), reports version skew and dead receipt roots, and names the lockfile gap. Supporting exports: bindings.LoadManifest, distribute.MarkerPrefix/ SectionBegin/SectionEnd. Read-only throughout; the receipt-fidelity write-path fixes (sideshow#92 hash retention, RecordResults wholesale replacement) are deliberately a separate change. Verified against the live store: found the pre-freeze beads-config install, a dead /tmp receipt root, and honest unavailable rows; exit 0 with zero structural failures. Closes: aae-orc-xteh (bd) Refs: sideshow#92, docs/doctor-spec.md
This file contains hidden or bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
Sign up for free
to join this conversation on GitHub.
Already have an account?
Sign in to comment
1 participant
Add this suggestion to a batch that can be applied as a single commit.This suggestion is invalid because no changes were made to the code.Suggestions cannot be applied while the pull request is closed.Suggestions cannot be applied while viewing a subset of changes.Only one suggestion per line can be applied in a batch.Add this suggestion to a batch that can be applied as a single commit.Applying suggestions on deleted lines is not supported.You must change the existing code in this line in order to create a valid suggestion.Outdated suggestions cannot be applied.This suggestion has been applied or marked resolved.Suggestions cannot be applied from pending reviews.Suggestions cannot be applied on multi-line comments.Suggestions cannot be applied while the pull request is queued to merge.Suggestion cannot be applied right now. Please check back later.
Consumers have no way to ask "is what sideshow recorded still true on this machine": the store can silently drift from its receipts, bindings can go stale, and the absence of a lockfile or defects feed today looks identical to a clean bill of health. This ships
sideshow doctor, the read-only report over sideshow's own records (bd aae-orc-xteh, orc charter F24 layer vocabulary), with a spec at docs/doctor-spec.md.Design points worth review attention:
--strictpromotes structural warns only, and advisory/unavailable never gate under any flag. One test row per branch of that table.Verified against the live store: it found the pre-freeze beads-config install (advisory, benign causes named), a dead /tmp receipt root (skipped with reason), and one false positive during development (custom-source sync entries) which is fixed and covered by a test. 19 top-level tests; lint clean; additive only, two tiny read-only exports (bindings.LoadManifest, distribute marker accessors).