Skip to content

docs(accuracy): clarify end-to-end guarantee design - #311

Open
zzylol wants to merge 1 commit into
mainfrom
docs/clarify-end-to-end-accuracy
Open

docs(accuracy): clarify end-to-end guarantee design#311
zzylol wants to merge 1 commit into
mainfrom
docs/clarify-end-to-end-accuracy

Conversation

@zzylol

@zzylol zzylol commented Aug 29, 2026

Copy link
Copy Markdown
Contributor

Why

Follow-up to #303. The accuracy design documented the data structures and formulas, but introduced key terms without explanation and did not give readers an end-to-end example connecting the problem to the proposed components.

What

  • Rewrites “Problem and why now” around a concrete two-layer error example.
  • Defines parameter configuration, final query result, combined error, and failure-probability budget in plain language.
  • Explains why TopK membership needs separation evidence rather than only small point-frequency errors.
  • Replaces “observable input” with an explicit input/output list.
  • Adds a complete EpsilonDelta candidate walkthrough from allocation through legality and cost ranking.
  • Adds a design overview assigning one responsibility to AccuracyTarget, AccuracyBudgetAllocator, AccuracyModel, and ResultGuarantee.
  • Removes schedule and cost questions from the Heilmeier section while retaining implementation risks in rollout/exit criteria.
  • Adds a developer-guide walkthrough and code-location map before traits and formulas.
  • Uses “final query result” and “guarantee evidence” consistently instead of undefined “caller-visible result” and “proof”.

Before this PR

The document moved directly from a terse problem statement to guarantee data structures. A reader had to infer what was being configured, what result was constrained, how local errors combine, and how the components connect.

After this PR

The design now introduces the flow before the representation:

query accuracy requirement
    -> local requirements
    -> concrete summary parameters
    -> local guarantees from those parameters
    -> composed final guarantee
    -> target check
    -> cost ranking of legal candidates only

A numeric example shows both acceptance and rejection, and the developer guide maps that flow to the implementing modules.

Verification

  • git diff --check
  • verified local design/developer cross-links and section structure
  • documentation-only change; code tests are not applicable

Scope

No accuracy formulas, planner behavior, or public interfaces change.

Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment

Labels

None yet

Projects

None yet

Development

Successfully merging this pull request may close these issues.

1 participant