Cyphrme / Cyphrme/Cyphr

Anchor resolution doc claims an unconditional guarantee

Open Beginner friendly
#159 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 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

Get new issues in your inbox

A short digest of beginner-friendly GitHub issues.