docs: define exact normalization contract

[hyfdev]

Summary

• document that normalization is exactly idempotent in the host-native encoded representation
• distinguish exact spelling from standard Path equality while retaining Node-style trailing separators and Windows drive-letter spelling
• enforce the contract through native, Windows prefix-like, WASIp1, and bounded public-model tests

Why

Standard Path equality compares components and can hide exact spelling differences such as . versus ./, foo versus foo/, and Windows drive-letter case. SugarPath already preserves those observable spellings, but the public documentation did not state the stronger fixed-point guarantee or explain that it is not a unique spelling for every Path-equal value.

Node.js publicly preserves trailing separators but does not guarantee exact idempotence for every Win32 input. These tests keep SugarPath's existing trailing behavior while explicitly protecting its stronger exact-output contract.

Validation

• cargo fmt --all -- --check
• cargo clippy --locked --workspace --all-targets --all-features -- -D warnings
• SUGAR_PATH_EXPECT_CACHED_CURRENT_DIR=0 cargo test --locked -p sugar_path
• SUGAR_PATH_EXPECT_CACHED_CURRENT_DIR=1 cargo test --locked --workspace --features cached_current_dir
• RUSTDOCFLAGS='-D warnings' cargo doc --locked -p sugar_path --all-features --no-deps
• package verification with and without cached_current_dir
• browser WASM checks and WASIp1 default/cached test compilation plus Clippy
• two independent adversarial reviews, both passed after all findings were addressed

Native Windows CI will execute the Windows-specific exact-output cases; local cross-target library checks passed.

[codspeed-hq]

Merging this PR will not alter performance

✅ 228 untouched benchmarks
⏩ 38 skipped benchmarks¹

---

_{Comparing agent/normalization-spelling-contract (3aa1f9b) with main (9ddede0)²}

Footnotes

1. 38 benchmarks were skipped, so the baseline results were used instead. If they were deleted from the codebase, click here and archive them to remove them from the performance reports. ↩

2. No successful run was found on main (6d809ec) during the generation of this report, so 9ddede0 was used instead as the comparison base. There might be some changes unrelated to this pull request in this report. ↩

[Copilot]

Copilot was unable to review this pull request because the user who requested the review has reached their quota limit.