Document actual formation triggers, zero values and configuration migration

[MasterOfBinary]

Current outcome

Correct both the README and this issue's earlier premise: zero maxima disable maximum triggers, not every way a batch can flush.

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 current behavior accurately: MinItems with satisfied MinTime can flush; MaxItems and MaxTime are maximum triggers; EOF flushes a remainder.
• State that MinItems:50 with MinTime:0 can flush at 50 even when maxima are zero; fewer than 50 on an idle non-closing source may wait indefinitely.
• Describe current conditional clamping only when maxima are nonzero; update to the chosen Bound stream execution and validate formation/resource configuration #73 validation/migration contract when it lands.
• Separate formation delay from time waiting for an execution slot and from handler duration.
• Use examples whose claimed output/grouping actually follows the configured timing/ordering contract.

Verification and completion

Check examples against current/final behavior with deterministic input fixtures. Cross-check README, Config.Get, package docs and migration notes.

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

Coordinate #73/#90/#94 and PR #67. Adjacent README edits in #67/#68 are merge coordination, not semantic prerequisites requiring those PRs to land first.

Design history

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

Original issue: README Configuration docs: zero MaxItems/MaxTime semantics and clamp rules still misdocumented

Post-#80 (and pending #67), the godoc on Config.Get is accurate, but README's Configuration section still misleads (validated @ 58cee73):

1. "MaxTime: Maximum time to wait before processing a batch" — never states that zero means disabled: with MaxTime/MaxItems unset there is no flush trigger at all, so a MinItems: 50-only config waits indefinitely until EOF. A real latency foot-gun that no user-facing doc discloses.
2. "If MinItems > MaxItems, MinItems will be set to MaxItems" (and the MinTime/MaxTime twin) — wrong for the default case: fixConfig (batch/batch.go:457-468) clamps only when the max is non-zero. With MinItems: 10, MaxItems: 0, MinItems stays 10; the doc's literal reading says it becomes 0→1.

Fix: qualify both clamp bullets with the non-zero-max condition and add one line stating zero max = no maximum/trigger, mirroring the merged Config.Get wording.

Sequencing: do this after PRs #67 and #68 land — both touch adjacent docs (#67 adds the ConfigValues field docs; #68 edits README elsewhere) and doing it now would conflict.