Document and test pointer error wrappers and errors.Is/As #91

Current outcome

Make error classification clear and correct. errors.As rejecting a value target when the dynamic error is a pointer is normal Go behavior, not an errors.As defect.

Replanned on 2026-09-06 against GoBatch master 63ef757 and ShitQuant's recorder, enrichment, paper/replay, and flow workloads. This is an implementation target, not a claim that the behavior already exists.

Required behavior

• Document the actual pointer-target idiom for emitted SourceError/ProcessorError and any new Preserve item/stage error identity and define reporting cardinality #79 item error.
• Test direct and multiply wrapped classification with errors.As and underlying-cause matching with errors.Is.
• Keep one canonical representation and update affected package docs/examples together.
• Do not require pointer-receiver breaking changes or classification helpers without an independent API need.
• Reconcile documentation already present in PRs fix(batch): panic recovery, deadlock-safe error sends, bounded prealloc, Done() race #65/docs: correct Nil processor description, errors.As guidance, and file structure #68 instead of duplicating it.

Verification and completion

Compile and run small error-classification examples for source/stage/item categories; verify wrapping retains causes and item identity where promised.

Follow the repository's formatting, race-test, vet/lint, package documentation, example and changelog requirements for the changed surface. Report the actual supported behavior and migration; do not treat a passing coverage percentage as proof of these outcomes.

Scope and relationships

Depends on the final #79 error shape. This issue is documentation/behavioral conformance, not a broad redesign of Go error matching.

Design history

The earlier report/prototype remains below for provenance; the requirements above supersede conflicting prescriptions. Existing discussion is preserved.

b.errs <- &SourceError{Err: err}
b.errs <- &ProcessorError{Err: err}

var pe batch.ProcessorError
if errors.As(err, &pe) { ... }