Cyphrme / Cyphrme/Cyphr

Module comment cites a witness-mode specification that was never written

Open
#161 0 comments 0 reactions 0 assignees View on GitHub
documentation
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

Get new issues in your inbox

A short digest of beginner-friendly GitHub issues.