Encapsulate bounded streaming group reduction¶

Status: Implemented in the local working tree and verified with the complete local gate. Test interfaces follow the existing contracts, with direct application/group tests as proposed to the user. This engineering specification preserves the approved commerce contracts.

Problem Statement¶

The streaming reducer coordinates group fields, aggregate counters, closures, nonlocal mutation, row extraction, partitioning, and persistence flushing in one method. Developers must mentally simulate shared state to modify it safely.

Solution¶

Encapsulate current-group invariants in a bounded accumulator, use typed row adapters, and give aggregate buffering a separate owner while retaining the existing work-store interface.

User Stories¶

As a developer, I want a single owner for current-group state, so that group transitions reset all relevant fields together.
As a developer, I want typed view and purchase adapters, so that row extraction no longer relies on Any callbacks.
As a operator, I want bounded distinct-product memory, so that oversized contexts cannot grow state without limit.
As a consumer, I want oversized groups excluded whole from pair evidence, so that partial groups cannot bias recommendations.
As a consumer, I want popularity retained for oversized groups, so that valid individual interactions still contribute.
As a evaluator, I want whole-group temporal partitioning preserved, so that holdout evidence cannot leak into training.
As a Commerce Property, I want geographic consistency checked per context, so that conflicting locations cannot mix evidence.
As a security maintainer, I want only derived summaries cross the persistence seam, so that raw interactions and context identifiers are never staged.
As a operator, I want exact integer and decimal arithmetic preserved, so that counts and purchase quantities remain stable.
As a operator, I want bounded asynchronous buffers and failure cleanup preserved, so that the refactor retains resource and failure guarantees.
As a tester, I want observable accumulator and work-store results, so that tests verify semantics rather than closures.

Implementation Decisions¶

Introduce a current-group accumulator owning group identity, product membership, row count, maximum event time, oversize state, and geography. Release raw identity when the group closes; never include it in emitted summaries.
Use typed view/purchase row adapters at the actual variation seam; keep online/offline Order grouping semantics unchanged.
Separate group summaries from a derived aggregate buffer that owns flushing thresholds and geographic contributions.
Preserve work-store consume methods, native counting strategies, resource ownership, deterministic sorting, exact arithmetic, and one-pass consumption.
Preserve whole-group holdout selection and category/global/geographic contribution rules.

Testing Decisions¶

Use existing work-store tests as the principal integration seam: reference reducer equivalence, whole-group holdout, oversize popularity, geographic counts, ordering rejection, cleanup, and asynchronous failure propagation.
Add direct accumulator behavior tests for group transitions and oversize boundaries without a database; test emitted derived summaries, not private state.
Run work-store and group-limit tests, end-to-end training tests, static checks, the complete suite, and installed-wheel verification.
Successful checks alone are insufficient: review the final implementation against every story, verify ownership moved into cohesive objects, and confirm duplicated decisions were removed.
Keep explicit validation guards when they communicate invariants; do not target an arbitrary count of conditional statements or introduce classes that merely forward calls.

Out of Scope¶

New counting backends, parallelism changes, arithmetic changes, source retention, increased resource limits, or altered ranking.

Further Notes¶

Preserve Commerce Scope isolation, snapshot-only serving, atomic publication, bounded resources, and exclusion of credentials and raw interaction identities from retained diagnostics. The refactor is complete only after implementation, focused verification, repository gates, and code-aligned documentation updates. PostgreSQL checks require an explicitly disposable database; record their omission if none is available. No deployment or hosted-setting change is authorized.