Make inbox bulk ops report partial progress and surface walk failures (CL-7207)

[TheGreatAxios]

Summary

Stacked on #486 (CL-7206, cl-7206-inbox-cursor-filter) — base this PR against that branch, not main, until it merges.

mark-all-read, clear-done, and /counts in packages/inbox/src/routes.ts shared a paging walk (listAllOpen) that silently break-ed the moment decodeMailboxListCursor returned null for a nextCursor it had just been handed — a rolling deploy landing two hub versions against @corbits/mailbox could change a cursor's shape mid-walk, and the caller would see a 200 having silently stopped partway through the inbox ({marked: 40} for a 5000-row inbox). mark-all-read and clear-done also mutated one item at a time with no transaction tying each item's writes together and no per-item error isolation: a throw on item N threw the whole handler as a 500, left items before N mutated, item N in a state the UI had never rendered (done-but-unread), and everything after N untouched, with no way for a retry to resume instead of re-walking and re-mutating from scratch.

Changes

• packages/inbox/src/walk.ts (new): extracts the paging walk into walkAllOpen, driven through an injected listPage so its failure modes are directly unit-testable. Throws IncompleteWalkError on an undecodable cursor, a cursor that doesn't advance, or exceeding MAX_WALK_PAGES (1000 pages × 100 rows/page = 100k rows) — instead of silently truncating or looping forever.
• packages/inbox/src/bulk.ts (new): extracts runBulkOperation, which applies a per-item action without letting one item's failure abort the rest, returning {succeeded, failed}.
• packages/inbox/src/routes.ts:
  • /counts, mark-all-read, clear-done route a failed walk through listAllOpenOrReport, which reports it via @corbits/error-sink and answers 500 with a refId instead of continuing with partial/wrong data.
  • mark-all-read's status flip + read flip run inside db.transaction so a throw between them never leaves a row half-mutated.
  • Both bulk routes now report {marked/cleared, failed, complete}. A 200 is reserved for failed === 0; any per-item failure answers 207 instead — a caller that only checks the HTTP status code (not the body) can no longer mistake a partial run for a complete one. This was added after a Critique pass flagged that a bare 200 with a failed count buried in the body doesn't satisfy "the caller must be able to tell a complete run from a partial one."

How a caller tells complete vs. partial

• 200 + {failed: 0, complete: true} — every eligible item was processed.
• 207 + {failed: N > 0, complete: false} — some items failed; marked/cleared says how many succeeded. The per-item failure is also reported through @corbits/error-sink with the item id, so a person can find exactly which rows failed and why.
• 500 + {error, refId} — the walk itself failed (undecodable cursor, non-advancing cursor, or the walk exceeded its page cap); no partial counts are returned because the eligible-item set itself couldn't be established.

Known test-coverage gap

Per-item failure and per-item catch-and-continue logic is fully unit-tested in bulk.test.ts against runBulkOperation directly, and the walk failure modes (undecodable cursor, non-advancing cursor, page cap) are fully unit-tested in walk.test.ts against walkAllOpen directly with injected listPage stubs — this is the mid-walk-failure test the ticket's outcome 4 asks for. What's not covered is a live-Postgres, route-level integration test that drives POST /mark-all-read or POST /clear-done through a genuine mix of succeeding/failing items and asserts the 207/{failed} response end-to-end — db in routes.test.ts is a Proxy stub (throws on any access), which can prove "the walk fails loudly" but can't fake a real per-item write failure without a live database. Flagging this rather than skipping silently.

Verification

• cd packages/inbox && bun run typecheck && bun test — 40 pass, 3 skip (pre-existing, DB-gated, unrelated), 0 fail.
• bunx prettier --check and bunx eslint on touched files — clean.
• Reviewed by Greybeard (approach) and Critique (implementation); Critique's one correctness-adjacent finding (the 200-always-for-partial-failure gap) is fixed in this PR.

Linear: CL-7207