[iliaal]

Rationale

Document the existing moveSheet() lifetime contract: a successful move invalidates every sheet wrapper and sheet-owned child, including unchanged-position sheets. Callers must re-fetch; failed moves leave wrappers usable, and workbook fonts/formats survive.

README example and ExcelBook reference now explain this. New test 259 covers XLS/XLSX sheet wrappers, XLSX filter children, failed moves, retained workbook objects and refetched data. Runtime code is unchanged; no changelog entry for this documentation/test-only change.

Validation

• Fresh strict native PHP 8.4.26 NTS / LibXL 5.2.0.1 build using repository developer flags; zero diagnostics.
• Full PHPT: 255 passed, 7 skipped, 0 failed/warned (262 total).
• Deliberately removing moveSheet's generation invalidation makes test 259 fail; restored implementation passes. Independent review executed the full README sequence and both format paths.
• Source claims traced to excel.c moveSheet() and sheet-generation guards; existing deleteSheet/load documentation remains distinct. Book docblock PHP lint and git diff --check pass.
• Remote full tree/modes 7ca18bcc6bffcec2197dcb959412a4adc5d1ede8 equals tested index. Actual merge-tree clean against current master and open sibling [Vulcan] Clarify nullable properties and indexed range warnings #337, whose files/lines are untouched.
• Test 259 is exercised by Tests workflow's PHP test lanes and Windows Build test lanes. Exact-head CI complete: Tests run 40186847882 and Windows Build run 40186847771 succeeded. All 36 executed jobs passed; one Windows release-upload job was intentionally skipped. All 36 logs verify merge checkout 674ffab, with final head c2924b6 and base 892940d. Workflow-security scan is path-filtered out.
• Audited summaries: PHP 8.4 Linux 253 passed / 9 skipped; ZTS 254 / 8; LibXL 4.6 229 / 33; Windows 8.4 x64 NTS 248 / 14. ASAN 8.6: 251 passed / 9 skipped plus two isolated passes. Zero test failures/warnings.

Limits

Local build used retained official headers/library with direct compiler invocation, not a fresh phpize/configure install. Seven license/platform skips are not passes. No local Windows, ZTS, sanitizer or performance claim. No runtime behavior changed.