docs: clarify config zero-value and clamp semantics

[MasterOfBinary]

Summary

Documentation and contract-locking tests for ConfigValues / Config semantics that were previously unstated or misstated. No behavioral code change.

Changes

• Config.Get godoc: the min→max clamp applies only when the corresponding max is > 0 (matching the engine's fixConfig); a zero max means "unset", no clamp. The previous wording implied the clamp was unconditional.
• MaxTime == 0 / MaxItems == 0: documented as "unset / disabled" (no time or count trigger). Previously counter-intuitive (zero reads like "immediately") and undocumented.
• MinTime == 0 (no minimum wait) and MinItems == 0 (engine treats as 1) documented.
• Contract-locking tests added: zero-value Get() round-trips, mutators accept zero/extreme values without panic, concurrent Get/Update under -race.

Testing

go test -race ./... green · go vet / gofmt clean. The new tests assert existing behavior to guard against future regressions of the now-corrected contract.

Backwards compatibility

Documentation plus additive tests only. No exported signature changed; no validation added that could reject existing inputs.

---

Part of a 5-PR set from a full-repo review; file-disjoint and independently mergeable in any order.

🤖 Generated with Claude Code

[gemini-code-assist]

Code Review

This pull request updates the batch configuration documentation to clarify how zero and conflicting values are handled by the engine. It also introduces several contract-locking tests to verify zero-value round-tripping, extreme value handling in mutators, and concurrent read/write safety. The review feedback suggests improving the robustness of the mutator tests by initializing the configurations with non-zero dummy values, ensuring that the mutators can successfully overwrite existing non-zero values with zero.

[gemini-code-assist]

The test currently initializes cfgUpdate and cfgSplit with nil (which defaults to all zero values). When testing with tc.values that contain zero values (like the "all zero" case), this doesn't actually verify that the mutators can overwrite existing non-zero values with zero. To make this contract-locking test robust, we should initialize the configs with non-zero dummy values first, ensuring that the update to zero is actually applied and verified.

			dummy := ConfigValues{
				MinItems: 99,
				MaxItems: 99,
				MinTime:  99 * time.Second,
				MaxTime:  99 * time.Second,
			}

			// Update: replaces all values at once.
			cfgUpdate := NewDynamicConfig(&dummy)
			cfgUpdate.Update(tc.values)
			if got := cfgUpdate.Get(); got != tc.values {
				t.Errorf("Update round-trip mismatch: expected %+v, got %+v", tc.values, got)
			}

			// UpdateBatchSize + UpdateTiming: the split setters must reach the
			// same state, with no clamping or rejection at the config layer.
			cfgSplit := NewDynamicConfig(&dummy)
			cfgSplit.UpdateBatchSize(tc.values.MinItems, tc.values.MaxItems)
			cfgSplit.UpdateTiming(tc.values.MinTime, tc.values.MaxTime)
			if got := cfgSplit.Get(); got != tc.values {
				t.Errorf("UpdateBatchSize/UpdateTiming round-trip mismatch: expected %+v, got %+v", tc.values, got)
			}

[codecov]

Codecov Report

✅ All modified and coverable lines are covered by tests.
✅ Project coverage is 96.73%. Comparing base (ba2a756) to head (1705ef2).

Additional details and impacted files

@@           Coverage Diff           @@
##           master      #67   +/-   ##
=======================================
  Coverage   96.73%   96.73%           
=======================================
  Files          12       12           
  Lines         368      368           
=======================================
  Hits          356      356           
  Misses          9        9           
  Partials        3        3           

☔ View full report in Codecov by Sentry.
📢 Have feedback on the report? Share it here.

🚀 New features to boost your workflow:

• ❄️ Test Analytics: Detect flaky tests, report on failures, and find test suite problems.