Track consumer API hardening for bounded batch, request and flow workloads

[MasterOfBinary]

Current outcome

This is a non-executable coordination issue for GoBatch's application-facing contracts. Keep focused issues authoritative and preserve the useful parts of the old review without treating every stylistic critique as required work.

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

• Track bounds/validation (Bound stream execution and validate formation/resource configuration #73), startup safety (Reject an empty effective processor chain before starting Batch #77), stage/item correlation (Preserve item/stage error identity and define reporting cardinality #79), output/failure semantics (Define stream filtering and fail-closed stage outcomes without silent loss #87), config updates (Wake active DynamicConfig waits and define atomic update boundaries #90), pointer-error usage (Document and test pointer error wrappers and errors.Is/As #91), and lifecycle/startup-mutation work.
• Record feat(batch)!: single-use Batch + Go returns (<-chan error, error); inline item IDs #64 as merged: IDs use a reader-local counter; repeated Go returns ErrBatchUsed. The remaining WithBufferConfig-after-start panic and analogous proposed options belong in the lifecycle issue.
• Require immutable startup options or explicit error-returning mutation rules; do not silently mutate a running instance.
• Keep package renaming, returning interfaces for mockability, hand-written Unwrap replacement and global factory rollout out of the current milestones.
• Retain ExecuteBatches local error aggregation as an optional measured optimization; CollectErrors stores all collected errors and is not a memory-bound promise.
• Track stream/request/flow delivery and release/pin evidence in focused child issues; this tracker is never a blocker and must never be marked codex-ready as an implementation task.

Verification and completion

Close only when the committed child outcomes and release evidence for the chosen tranche are complete; deferred ideas do not become implementation obligations. Each child owns its actual code checks.

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

Preserves the existing review tracker and comment history. Focused follow-ons: #95 lifecycle, #96 bounded-core release, #97 flow delivery epic, #98 flow runtime, #99 standalone flow release and #100 optional request/flow composition. No root-package rename or OnyxCore dependency.

Design history

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

Original issue: API hardening & cleanup (ROAST.md architectural review)

Summary

Tracker for the API/code-quality points raised in an architectural review (the abandoned ROAST.md from PR #58). Each point is annotated with its current status on master (66070eb) so the still-live items are actionable and the already-fixed ones are recorded.

Tone of the original was deliberately harsh ("a grumpy senior staff engineer"); the substance is summarized neutrally below.

Status of each point

#	Critique	Status
1	Item.Data was interface{} everywhere → no compile-time type safety	✅ Fixed — generics migration (#60); master is Batch[T], New[T any].
2a	A whole goroutine + buffered channel (doIDGenerator, b.ids, IDBufferSize) just to increment a counter	⏳ In progress — open PR #64 replaces it with an inline sync/atomic counter and removes the IDBufferSize API.
2b	ExecuteBatches locks a mutex per error (batch/helpers.go:119)	⚠️ Still live — collect errors in a local slice per goroutine and append once.
3	IgnoreErrors spawns a goroutine that leaks if the channel never closes; errors.go hand-rolls Unwrap()	🟡 Partial — master now nil-guards the channel (avoids the nil-channel leak); the "never-closed channel" case is caller-owned. Revisit Unwrap vs %w if desired.
4	fixConfig silently mutates input (MinItems: 0 → 1, batch/batch.go:453)	⚠️ Still live — prefer validating and returning an error (or a documented default) over silent rewrite. Tracked jointly with the resource-limits + config-validation issue.
5	batch.Batch stutters; core API could live in root gobatch so callers write gobatch.New()	🟡 Design decision — would be a breaking rename; reasonable for a v0 but needs a deliberate call.
6a	New returns *Batch (concrete) rather than an interface, hurting mockability	🟡 Design decision — master: func New[T any](config Config) *Batch[T].
6b	Library panics instead of erroring: WithBufferConfig after Go() (batch.go:113) and concurrent Go() (batch.go:240)	⚠️ Still live — APIs should be hard to misuse, not booby-trapped: return errors, or make buffer config immutable at construction (functional options).

Actionable items (still live)

• 2b — Stop locking per-error in ExecuteBatches; accumulate locally, merge once.
• 4 — Validate config instead of silent mutation (with the resource-limits/validation work).
• 6b — Replace library panics with returned errors and/or immutable-at-construction config.
• (optional) 3 — Reconsider IgnoreErrors contract / use fmt.Errorf("%w", …).
• (optional) 5 / 6a — Decide on package/type naming and concrete-vs-interface return as part of the path to v1.

Source (for recovery — branch is being deleted)

roast-codebase-7386035102356312858 @ PR #58 (ROAST.md). PR is closed but its diff remains viewable.

---

Related: #73 (resource limits + config validation — point #4 lands there)

[MasterOfBinary]

Status update vs master @ 58cee73 (the annotations above predate the #64 merge):

• 2a DONE — feat(batch)!: single-use Batch + Go returns (<-chan error, error); inline item IDs #64 merged: inline item IDs, ID goroutine and IDBufferSize removed.
• 6b HALF DONE — second/concurrent Go() now returns ErrBatchUsed (feat(batch)!: single-use Batch + Go returns (<-chan error, error); inline item IDs #64); WithBufferConfig after Go() still panics (batch/batch.go:125). Note PR feat(batch): configurable context-cancellation mode (WithCancelMode) #76 adds a same-pattern WithCancelMode panic — if 6b is resolved, both should convert together.
• 4 lands via Bound stream execution and validate formation/resource configuration #73 (validation); PR docs: clarify config zero-value and clamp semantics #67 documents the clamp semantics in the meantime.
• 2b still live and only tracked here: ExecuteBatches locks the mutex per error in batch/helpers.go — accumulate locally, merge once under one lock.
  Remaining actionable: 2b, 6b remainder. Optional: 3 (Unwrap is idiomatic Go — suggest dropping), 5/6a (v1 naming/interface decisions). ROAST.md itself was never committed (recovered from closed PR Add architectural critique (ROAST.md) #58), which is fine — this issue is its tracker.