Cancellation contract, atomic IDs, and ItemError refactor

[MasterOfBinary]

Summary

This PR refactors the core batch pipeline around three related improvements:

• ItemError type — per-item errors (where item.Error != nil after a processor returns) are now reported as *ItemError instead of *ProcessorError. ItemError carries the failing item's ItemID so callers can correlate errors with specific items. Processor-wide errors (returned as the second value of Processor.Process) remain *ProcessorError.
• Atomic ID counter — the dedicated ID-generator goroutine and its channel buffer (BufferConfig.IDBufferSize, DefaultIDBufferSize) are removed. Item IDs are now generated with sync/atomic, eliminating a goroutine, simplifying startup, and removing a class of coordination bugs.
• Context-aware cancellation contract — waitForItems now honors ctx.Done() (previously ignored, delaying shutdown by up to MaxTime). Cancellation drains items one-by-one so partial batches are returned during shutdown. A send-on-closed-channel race window is closed: doProcessors now waits for b.items to drain before exiting, preventing panics when doReader is still alive as b.errs closes. time.After replaced with time.NewTimer + defer Stop() to prevent timer leaks.

Full details — including a migration guide and errors.As switch example — are in the [Unreleased] section of CHANGELOG.md.

Breaking changes

• *ItemError replaces *ProcessorError for per-item errors — update any errors.As switches (see CHANGELOG migration guide).
• BufferConfig.IDBufferSize and DefaultIDBufferSize removed — drop from any BufferConfig struct literals.
• Partial batches (smaller than MinItems) may now be returned during shutdown.

Test plan

• go build ./... — passes
• go vet ./... — passes
• go test -race -coverprofile=coverage.txt -covermode=atomic ./... — passes (batch: 97.9%, processor: 98.2%, source: 95.8%)
• New cancellation contract test suite in batch/ covers the race window, context-awareness, and partial-batch drain behaviour

Out of scope

The High-priority panic-handling cleanup flagged in CONCERNS.md (unrecovered panics from goroutines crashing the process) is intentionally excluded from this PR and will be addressed in a follow-up MR.

[codecov]

Codecov Report

✅ All modified and coverable lines are covered by tests.
✅ Project coverage is 96.31%. Comparing base (66070eb) to head (56779b9).

Additional details and impacted files

@@            Coverage Diff             @@
##           master      #62      +/-   ##
==========================================
- Coverage   96.79%   96.31%   -0.48%     
==========================================
  Files          12       12              
  Lines         374      380       +6     
==========================================
+ Hits          362      366       +4     
- Misses          9       11       +2     
  Partials        3        3              

☔ View full report in Codecov by Sentry.
📢 Have feedback on the report? Share it here.

🚀 New features to boost your workflow:

• ❄️ Test Analytics: Detect flaky tests, report on failures, and find test suite problems.

[gemini-code-assist]

Code Review

This pull request introduces significant improvements to the GoBatch pipeline, primarily focusing on robust context cancellation and refined error handling. Key changes include making waitForItems context-aware to ensure proper drainage of buffered items during shutdown, replacing the dedicated ID-generator goroutine with an atomic counter for better performance and simplicity, and introducing a new ItemError type to explicitly distinguish per-item failures from processor-wide errors. Documentation and examples have been updated to reflect these changes, and new tests were added to verify cancellation behavior and error reporting. I have no feedback to provide as the changes are well-implemented and documented.

[MasterOfBinary]

Superseded by #64; breaking changes reverted per maintainer direction.