Add lightweight observation hooks for bounded batch execution #70

Summary

Add optional, zero-overhead-by-default observability to GoBatch: pluggable logging and runtime statistics/metrics. This captures work from two abandoned branches so it isn't lost.

Motivation

Today there's no way to see what a Batch is doing or to measure throughput/error rates without wrapping processors by hand. Two prior explorations tackled this from different angles; this issue tracks reconciling them into one design.

A. Pluggable Logger

Two candidate interface shapes were prototyped — pick one (or support both via adapters):

Minimal, dependency-free (from cursor/implement-backwards-compatible-logger-hooks-3373 @ a58bbf8) — compatible with log.Logger, slog, zap.SugaredLogger, etc.:

type Logger interface {
    Printf(format string, v ...interface{})
}
// default: silent noopLogger; attached via b := batch.New[T](cfg).WithLogger(log.Default())

Leveled (from feature/logger-stats @ e9a7c6f, local-only):

type Logger interface {
    Log(level LogLevel, format string, args ...interface{})
    Debug(format string, args ...interface{})
    Info(format string, args ...interface{})
    Warn(format string, args ...interface{})
    Error(format string, args ...interface{})
}
// built-ins: NoOpLogger (default, zero overhead), SimpleLogger (stdout/stderr + timestamps)

The batch would log: processing start/completion, source-read progress, per-batch details, and errors as they occur. A logging processor wrapper was also prototyped (processor/logging.go).

B. StatsCollector / runtime metrics

From feature/logger-stats @ e9a7c6f (batch/stats.go):

type StatsCollector interface {
    RecordBatchStart(batchSize int)
    RecordBatchComplete(batchSize int, duration time.Duration)
    RecordItemProcessed()
    RecordItemError()
    RecordSourceError()
    RecordProcessorError()
    GetStats() Stats
}
// built-ins: NoOpStatsCollector (default), BasicStatsCollector (thread-safe in-memory counters/timings)
// Stats: aggregated counts, durations, throughput, success/error rates

Plus a stats processor wrapper (processor/stats.go).

Design notes / open questions

• Default must be noop with zero overhead (both prototypes did this).
• Logging vs. metrics are arguably two concerns — this issue can be split into two if preferred.
• Both prototypes predate the generics migration (feat: migrate GoBatch API to generics #60); APIs need to be made generic (Batch[T]) on adoption.
• Decide minimal-Printf vs. leveled Logger (or ship minimal + a leveled adapter).

Source (for recovery — branches are being deleted)

• feature/logger-stats (local commit e9a7c6f, ~2,100 LOC incl. LOGGING_STATS.md, batch/logger.go, batch/stats.go, processor/logging.go, processor/stats.go) — the fuller proposal; remote was already deleted, so this commit existed only locally.
• cursor/implement-backwards-compatible-logger-hooks-3373 (commit a58bbf8, batch/logger.go minimal interface).