Anchor resolution doc claims an unconditional guarantee
- Dominant language
- Rust
- Stars
- 3
- Forks
- 0
- Avg merge
- 1d 42m
- Merged PRs (30d)
- 11
Description
The doc comment on `resolve_anchor_position` in `rs/cyphr-storage/src/engine/mod.rs:416-419` states that every downstream branch fails closed behind the sync channel's post-apply authenticated comparison, or behind "the chain-verification gap case". Both halves of that claim are weaker than written.
**The post-apply comparison is conditional.** It runs only when an authority identity is configured. A deployment that runs the witness without one — which the server explicitly supports, emitting a startup warning rather than refusing — does not get that closure. The comment asserts it unconditionally.
**The second closer is not defined anywhere.** Searching the tree for "chain-verification gap case" returns exactly this one occurrence. A reader cannot follow it to a mechanism, a test, or another comment, so the claim rests on a term that exists only in the sentence making it.
No test exercises the cross-principal anchor path against the unauthenticated sync configuration, so nothing currently distinguishes the documented behavior from the actual behavior.
## Scope, stated honestly
This is a documentation defect, not new exposure. The underlying risk under unauthenticated sync is already documented and accepted — the server warns about it at startup, and the anchor scoping question it touches is tracked separately in #154. Nothing here says the system behaves worse than believed; it says a comment claims a guarantee that is conditional and cites a closer that does not exist.
The reason to fix it rather than leave it: a reader auditing this path will take the comment as establishing the property, and stop. That is the specific failure mode this comment produces.
## Why it is worth citing
This exact paragraph was rewritten in `a181406` to correct a *different* overclaim in the same doc block — the previous version asserted the anchor was principal-scoped, which was disproved by resolving one principal's anchor against another's chain. The edit that corrected that claim restated this one unchanged.
That makes it a clean example of the pattern that dominated review findings on this work: not broken logic, but assertions that nothing checks. The implementations were correct; the suites were green; what repeatedly shipped was documentation and conditions claiming properties no evaluator closed. The highest-yield question on this codebase is therefore not "is this right?" but "what does this claim, and what checks it?" — asked of comments and condition text as much as of code.
## Suggested shape
State the closure with its actual precondition (an authority identity is configured), and either define the second closer where it can be found or drop it. If the unauthenticated configuration genuinely has no closure on this path, say that plainly — an accurately documented gap is more useful than an inaccurately documented guarantee.
Contributor guide
No contributing guide indexed for this repository
Research direction
Read the doc comment at rs/cyphr-storage/src/engine/mod.rs:416-419, then search the tree for "chain-verification gap case" and inspect the server's unauthenticated-sync warning. Revise the comment to state the authority-identity precondition and define or remove the unsupported closer; done means the documented guarantee matches the implementation and no undefined term remains.
Written by the indexing model from the issue text.
Assessment
- Tech stack
- rust
- Domain
- documentation, security
- Issue type
- Documentation
- Difficulty
- 2/5
- Estimated time
- 1-3 hours
- Activity status
- Quiet
- Clarity
- Clearly specified
- Newbie friendliness
- 78/100