Skip to content

Compile Swimlane steps once for snapshot resolution

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

Swimlane resolution repeats geography, recent-seed, and anchor decisions when collecting lookup variations and when selecting candidates. A new strategy can change one branch while leaving the other inconsistent.

Solution

Compile configured steps into cohesive resolved step objects that declare snapshot variations and resolve their candidates. Ordinary and recent-history behavior uses composition behind one small interface.

User Stories

  1. As a developer, I want step decisions compiled once, so that snapshot requests and candidate resolution cannot disagree.
  2. As a developer, I want ordinary and recent step strategies, so that new variation behavior has a clear owner.
  3. As a consumer, I want configured step order retained, so that fallback ordering and provenance remain stable.
  4. As a consumer, I want all steps resolved from one serving head, so that one response cannot mix snapshots.
  5. As a Shopper, I want typed recent views and purchases preserved, so that each recent strategy uses the correct evidence.
  6. As a consumer, I want missing geography or anchors yield empty steps, so that later configured fallbacks can still run.
  7. As a consumer, I want unavailable steps still observe the serving head, so that missing snapshots remain distinguishable from empty results.
  8. As a Shopper, I want authorized view history used only as final filler, so that history access remains bounded and lazy.
  9. As a consumer, I want deduplication, eligibility, quota, and purchase filters preserved, so that the same requested lane produces the same selections.
  10. As a tester, I want public resolution tests cover mixed step types, so that the compiler need not be tested through private branches.

Implementation Decisions

  • Compile each step once using request geography, anchor, and bounded authorized profile seeds. Use ordinary and recent step implementations with variation and candidate operations.
  • Represent unavailable steps as empty resolved steps; preserve configured positions and provenance.
  • Collect all required variations and perform the existing single-head lookup. Preserve the head-only fallback lookup when every step is unavailable.
  • Leave ordered composition and its final history fallback as the owners of quota and cross-step filtering.
  • Keep public resolution arguments, result type, seed caps, evidence filtering, and candidate ranking unchanged.

Testing Decisions

  • Use existing Swimlane resolver/composition and HTTP contract tests; retain geographic recent-view and recent-purchase coverage.
  • Add mixed ordinary/recent tests, missing geography/anchor tests, empty-seed/head behavior, and lazy eligible history fill with exact expected IDs and provenance.
  • Run focused Swimlane tests, API contracts, static checks, the full 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 Swimlane strategies, different seed weights, changed authorization, geography normalization, storage migrations, and recommendation algorithms.

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.