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

[MasterOfBinary]

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.

Original issue: errors.As with a value target never matches SourceError/ProcessorError

The engine emits pointer errors (batch/batch.go:385,427,433):

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

but the godoc on Batch says errors "will be of type SourceError / ProcessorError" (batch/batch.go:42,82), so the natural user code

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

silently never matches — *ProcessorError is not assignable to ProcessorError. Every error classifies as "other".

Fix options (decide once, before the v1 freeze):

1. Commit to pointer identity: pointer receivers on Error/Unwrap, document the errors.As(err, &target) pointer-target form everywhere.
2. Ship IsSourceError(err) / IsProcessorError(err) helpers and steer docs to those.

PRs #65/#68 add doc clarifications only; the type-identity decision is design work that belongs with the error-plane redesign (#79, #87).

Found in the 2026-07-10 full-repo review.