Module comment cites a witness-mode specification that was never written
- Dominant language
- Rust
- Stars
- 3
- Forks
- 0
- Avg merge
- 1d 42m
- Merged PRs (30d)
- 11
Description
The module documentation at the top of `rs/cyphr-server/src/sync.rs` points readers to `docs/specs/witness-mode.md` for the normative account of witness sync. That file does not exist in the repository, and this is its only inbound reference — so nothing else would surface the gap.
This matters more than a dead link usually would, because `sync.rs` is where the repository states, in its own voice, that a correctly-signed witness response cannot be distinguished from a live one by any comparison of wire fields against each other or against local state. That is a substantive claim about what witness sync does and does not guarantee, and the module comment routes a reader to a file that would presumably carry it normatively. A reader following the pointer gets nothing.
The file was never written, rather than written and lost: `git log --all` for that path returns nothing, so no commit reachable from any branch has ever touched it. That rules out restoring it from history and leaves two repairs — write the specification the comment promises, or drop the reference and let the module comment carry the guarantee statement directly.
To reproduce:
```
ls docs/specs/witness-mode.md
git log --oneline --all -- docs/specs/witness-mode.md
grep -rn "witness-mode.md" --include='*.rs' --include='*.md' .
```
The last command returning a single hit is the point: there is no second reference to cross-check the intent against.
Contributor guide
No contributing guide indexed for this repository
Research direction
Read the module documentation in rs/cyphr-server/src/sync.rs and run the listed checks for docs/specs/witness-mode.md, its git history, and inbound references. Decide whether the repository should gain the promised normative specification or remove the reference while preserving the guarantee statement; done means the pointer no longer leads to a missing file.
Written by the indexing model from the issue text.
Assessment
- Tech stack
- rust
- Domain
- documentation
- Issue type
- Documentation
- Difficulty
- 5/5
- Estimated time
- Over a week
- Activity status
- Quiet
- Clarity
- Mostly clear
- Newbie friendliness
- 45/100