Walk a share in the order the resume position is read in (#189)

[richardmhope]

Fixes #189.

A reclaimed file-share task could skip files and report the scope clean — silent coverage loss, the worst way this scanner can be wrong.

The defect

fetch resumes by dropping every entry whose key sorts at or before the stored position. That is only sound if the walk hands files over in that same order, and it did not: _walk yielded a directory's own files while scanning the listing and merely pushed subdirectories, so every file in a directory went out ahead of everything beneath a subdirectory sorting before them — and within the directory they went out in reverse, since the loop iterated the reversed batch the stack was meant to pop in order.

Reproduced against merged main, with a/x.txt (holding an AWS key), b.txt, m.txt:

yield order          : ['m.txt', 'b.txt', 'a/x.txt']
resume after 'b.txt' : ['m.txt']          # re-delivered
NEVER SCANNED        : {'a/x.txt'}        # and coverage called the root complete

The fix

• One order for the whole root. Files are stacked alongside directories instead of yielded on the spot, so a subdirectory's subtree is walked before the siblings that sort after it.
• The position is compared segment by segment, not as a joined string. / (0x2F) sorts after . (0x2E), so "a/b" > "a.txt" as strings while the walk yields a/b first — comparing whole keys would have dropped a.txt on resume, reintroducing the same class of bug in a different shape. There is a test for exactly these names.
• Checkpoint version 1 → 2. A stored 1 position names a place in an order this engine does not walk, so it is discarded and the root re-read. Re-reading costs a pass; misreading costs coverage.

Validation

• Three regression tests, each confirmed to fail against the pre-fix connector: the reported skip, the /-vs-. ordering trap, and the discarding of a 1 checkpoint.
• The conformance kit now covers this connector. assert_checkpoint_resume exists for precisely this defect and was never invoked here, though Confluence and Jira both call it — Fileshare checkpoint resume can silently skip files: walk order does not match the resume comparison #189 called that out as the reason the suite missed the bug. It now runs against a nested fixture, and against the old code it reports: "resuming from a published checkpoint did not continue where it left off (2 unit(s) skipped, 1 re-yielded)".
• Fuzzed 300 randomly generated trees over adversarial names (a, a.txt, a.b, a-b, a_, a~), resuming from every cut point of every tree: zero non-ascending orders, zero resumes that skipped or repeated.
• ruff / ruff format / mypy / make docs-check clean; full suite 1944 passed, 2 skipped (the two permission-bit tests, correctly skipped as root here; CI runs them).

Docs

docs/connectors.md said the walk was "sorted at every level" — true of each individual listing, and yet the order was still wrong, which is roughly the ambiguity the bug hid behind. It now states the actual guarantee (one order across the root), the segment-wise comparison and why, and the version bump. CHANGELOG gains a Fixed entry.

Operator note

No action required. In-flight 1 checkpoints are discarded automatically, costing one re-read of the affected root. Findings already stored are unaffected — this changes only the order files are handed over in, not their identity.

🤖 Generated with Claude Code

https://claude.ai/code/session_012sohE85sRDt6t2w3936rGJ

---

Generated by Claude Code

[icebergai-review-bot]

Verdict

APPROVE

Completed bounded review across 1 immutable scope(s). No actionable findings in the supplied change.

Scope health

Convergence: healthy. Review mode: initial.
Recommended action: CONTINUE_INCREMENTAL.

• No escalation signals.

Prior findings

Finding	Status
—	No prior finding state

New findings

No new findings.

Fix-induced regressions

• None evidenced.

Uncertainty

• No material uncertainty recorded.

Validation

• Reviewed the exact supplied diff and exact-head connector context.
• Verified the revised depth-first traversal order matches segment-wise checkpoint comparison and that v1 checkpoints restart safely.

Residual risks

• None identified.