docs: clarify semantic control documentation

[hayabusa-cloud]

Summary

This PR clarifies the public iox semantic-control documentation for ErrMore, ErrWouldBlock, and real failures. It documents count-first handling, helper-based classification, and the boundary between wrapped API classification and exact hot-path sentinel dispatch.

Changes

• Clarifies package GoDoc so callers prefer iox semantic helper predicates over direct errors.Is calls when classifying iox semantic-control outcomes.
• Updates READMEs with the example control loop using iox.IsMore(err) and iox.IsWouldBlock(err).

[codecov]

Codecov Report

✅ All modified and coverable lines are covered by tests.

📢 Thoughts on this report? Let us know!

[Copilot]

Pull request overview

This PR clarifies iox’s semantic-control model (ErrMore / ErrWouldBlock vs real failures), documents “count-first” handling and helper-based classification, and codifies the boundary between wrapped API classification and exact-sentinel hot-path policy dispatch.

Changes:

• Documented semantic-control classification guidance across GoDoc and READMEs (including canonical control-loop examples).
• Added IsFailure(err) predicate and expanded semantics tests around classification.
• Added a policy test asserting wrapped ErrMore is returned (classifiable via errors.Is) but does not trigger exact-sentinel policy retry.

Reviewed changes

Copilot reviewed 10 out of 10 changed files in this pull request and generated 2 comments.

Show a summary per file

File	Description
semantics.go	Adds IsFailure and clarifies Outcome/Classify semantics regarding numeric ordering and wrapped sentinels.
semantics_test.go	Extends predicate/classification test matrix and adds a wrapped-ErrMore classification test.
policy_test.go	Adds coverage that wrapped ErrMore does not trigger exact-sentinel policy retry behavior.
io.go	Clarifies CopyN’s “bounded copy exactly n bytes” abstraction boundary in docs.
doc.go	Expands package-level documentation on semantic errors as control outcomes and helper-based classification.
README.md	Updates English docs with count-first guidance, canonical loop, helper-based classification, and exact-sentinel dispatch notes.
README.zh-CN.md	Mirrors the clarified semantics docs and examples in Simplified Chinese.
README.ja.md	Mirrors the clarified semantics docs and examples in Japanese.
README.fr.md	Mirrors the clarified semantics docs and examples in French.
README.es.md	Mirrors the clarified semantics docs and examples in Spanish.