Generate and serve property-local commerce recommendations

Document control

• Specification status: APPROVED as the authoritative implementation baseline.
• Decision requested: None; downstream technical design may begin.
• Source authority: Product Vision & Strategy Brief revision 0.16, approved by the Sponsor on 2026-08-05.
• Behavior boundary: The approved V1 baseline governs six property-local strategies; the additive contract below governs category/geographic strategies and configured Swimlanes.
• Repository scope note: Later additive personalization and simulation capabilities are governed by their dedicated implementation documents. Their presence does not revise this approved base snapshot contract or make personalization part of the six-strategy Training Run.
• SDD posture: Spec-anchored, living, standard rigor for a maintained internal service.
• Revision lineage: Revision 0.15 adds the Sponsor-requested category/geographic Swimlane contract; revision 0.14 makes bounded co-occurrence group limits deployment-configurable; revision 0.13 makes in-store/offline purchases optional.

Decision and strategic trace

Intent summary

• Target actor: Commerce operators and downstream systems integrating recommendation training and retrieval.
• Opportunity: Produce reusable, evidence-aware Item-to-Item and property-wide Recommendation Sets without requiring each store or marketplace to build recommendation infrastructure.
• Desired user outcome: An authorized consumer can request a property-local Training Run and later retrieve versioned recommendations with ranking and provenance.
• Desired business outcome: Multiple Commerce Properties can use one product without behavioral pooling or source-schema lock-in.
• Success measures: Temporal holdout Recall@K and NDCG@K by property and strategy; catalog coverage, popularity concentration, fallback rate, and performance by Item-support cohort; later controlled downstream outcome tests.
• Guardrails: No cross-property or cross-Catalog recommendations; no failed Training Run may replace a currently available snapshot; fallback provenance remains observable.

Upstream trace

Source	Approved intent	Specification consequence
D-002, D-003	Item-to-Item co-occurrence with same-Order and same-session boundaries	FBT and Also Viewed have distinct mandatory grouping contexts.
D-004, D-005, D-007	Evidence-gated fallback, temporal evaluation, property-local behavior	Fallback is strategy-specific and must be evaluated by cold-support cohort.
D-006	Six first-version strategies	No additional personalized strategy is in scope.
D-008	Training API, relational batch generation, Serving API	Training and retrieval are product behavior, while scheduling remains external.
D-009, D-010, D-014	Engine-neutral configured streaming reads	Source schemas are mapped to canonical rows that are consumed incrementally without request-supplied SQL or raw-data staging.
D-011, D-012	Composite identities and hard Catalog boundary	Every run and output is scoped by data source, Tracking ID, and Catalog ID.
D-013	Mandatory Order ID and Session ID	Missing grouping keys prevent the affected strategy from being validly trained.
D-015	Minimum per-Catalog capacity profile	Qualification covers hundreds of thousands of Products, at least 100 million views, at least 100 million purchases, and at least two years of history without raw-data staging.
D-016	Completion, latency, and availability objectives	V1 quality evidence must demonstrate the approved batch and API service levels.
D-017	Bounded co-occurrence group contribution	Oversized Browsing Sessions and Orders cannot create unbounded pair growth, but their rows continue to inform applicable popularity strategies.
D-018	Optional in-store/offline purchases	Online purchases remain required; a merchandiser may additionally configure in-store/offline purchases, and Order grouping remains channel-scoped.

Strategic non-goals

• Shopper-specific personalization.
• Cross-property behavioral pooling or cross-Catalog Recommendation Sets.
• Catalog management, commerce operations, recommendation presentation, or external scheduling.
• Synchronous calculation of recommendation models during Serving API retrieval.
• Claiming business impact solely from offline evaluation.

Evidence, scope, and baseline

Evidence states

Facts

• FACT-1: The repository contains no existing recommendation behavior or public contract; this is greenfield behavior.
• FACT-2: The Sponsor approved strategic revision 0.16 on 2026-08-05.

Interpretations

• INT-1: A Recommendation Snapshot must be an atomic serving boundary because the approved source prohibits failed Training Runs from replacing a working snapshot.
• INT-2: Database neutrality requires a canonical streaming-read contract, not identical SQL across every engine.

Assumptions and hypotheses

• ASM-1: Configured source dialects can stream the canonical fields with stable semantics; validate through compatibility tests for each supported adapter.
• ASM-2: The selected fallback hierarchy will outperform simpler baselines for at least some cold-support cohorts; validate through the approved temporal evaluation standard.
• ASM-3: Item Metadata is sufficiently complete to support Similar Items and cold-item fallback; validate by property before publishing those outputs.

Intent decisions

• DEC-1: Approved decisions D-001 through D-018 in strategic revision 0.16 govern this specification.
• DEC-2: The Sponsor selected asynchronous Training API execution on 2026-08-05: submission returns a Training Run identity without waiting for completion, and status is observable separately.
• DEC-3: The Sponsor classified both APIs as trusted internal interfaces and excluded authentication and authorization from the first-version specification on 2026-08-05.
• DEC-4: The Sponsor selected one active Training Run per data-source, Tracking ID, and Catalog ID boundary; same-key repetition returns the existing run, a conflicting submission reports the active run, and cancellation is excluded from V1.
• DEC-5: The Sponsor selected structured snapshot_not_found behavior before first publication, valid empty lists with insufficient_evidence when a snapshot lacks eligible results, and continued serving of stale snapshots marked with freshness metadata. The default stale threshold is 48 hours and is property-configurable.
• DEC-6: The Sponsor selected all-or-nothing snapshot publication. Insufficient interaction evidence is a valid empty strategy outcome; missing mandatory fields, invalid boundaries, streaming-read failure, or strategy computation failure fails the run. New results are never combined with strategies copied from an older snapshot.
• DEC-7: The Sponsor selected a Serving API result limit from 1 through 100 with default 20, no pagination in V1, descending score order, and ascending Product ID as the deterministic equal-score tie breaker.
• DEC-8: The Sponsor placed Data Source Adapter onboarding outside V1 API behavior. Deployment configuration provisions connections, dialect drivers, read mappings, and stable data-source identities; the Training API references an existing data_source_id.
• DEC-9: The Sponsor required canonical rows to be consumed directly as a stream from the relational source, with no extracted or staged raw interaction dataset. The service retains the five most recent successful snapshots per property/catalog and serves only the latest; it retains Training Run metadata and metrics for 90 days and failed-run diagnostics for 30 days. These retention values are deployment-configurable.
• DEC-10: The Sponsor set a minimum V1 per-Catalog qualification profile of hundreds of thousands of Products, at least 100 million view rows, at least 100 million purchase rows, and at least two years of history. These values qualify the implementation and do not impose hard ingestion limits.
• DEC-11: At the approved qualification profile, the Sponsor selected Training Run completion within 12 hours; Training submission and status p95 latency at most 500 ms; Serving API p95 latency at most 90 ms and p99 latency at most 150 ms; monthly Serving API availability of at least 99.9%; and monthly Training API availability of at least 99.5%.
• DEC-12: The Sponsor selected deployment-configurable maximum co-occurrence group sizes, defaulting to 100 distinct Products per Browsing Session and 200 per Order. Both configured limits must be positive. A group above its applicable limit is excluded whole from co-occurrence and category-pair evidence, while its rows still contribute to Most Viewed, Best Sellers, and Trending as applicable; Training Run metrics disclose every exclusion.
• DEC-13: The Sponsor made online purchases the required purchase input and in-store/offline purchases optional. When configured, both channels contribute to purchase-driven strategies, but orders from different channels are never combined solely because they share an Order ID.

Scope

In scope

• Requesting and observing a Training Run for one property-local recommendation boundary.
• Reading Catalog, view, and Online Purchase data plus optional Offline Purchase data through a saved Data Source Adapter configuration.
• Validating canonical identity and grouping fields.
• Producing Frequently Bought Together, Also Viewed, Similar Items, Best Sellers, Most Viewed, Trending, and the five category-constrained strategies described below.
• Applying strategy-specific fallback behavior and recording Recommendation Provenance.
• Persisting and retrieving versioned Recommendation Snapshots.
• Retaining the last available snapshot when a later Training Run fails.

Out of scope

• Interactive source-query authoring through the Training API.
• Live event ingestion, continuous training, or pipeline-owned scheduling.
• Cross-Catalog or cross-property discovery.
• Recommendation display, experimentation assignment, or conversion attribution.
• API-based creation or mutation of Data Source Adapter configurations.

Approval-time baseline and unchanged external ownership

• Approval-time baseline (2026-08-05): No product behavior existed; main.py was a generated Python starter. This is historical discovery evidence, not a description of the current tree.
• Required change: The observable Training API, Training Run lifecycle, Recommendation Snapshot publication, and Serving API behavior specified here are now implemented; source, migrations, and tests remain authoritative for the as-built details.
• Unchanged behavior: External systems continue to own source-data loading, scheduling, commerce operations, and recommendation presentation.

Actors, permissions, and domain language

Actors and permissions

Actor	Permitted behavior	Prohibited behavior
Training Caller	Request and inspect Training Runs for a configured property/catalog boundary.	Supply arbitrary read SQL or broaden the boundary of an accepted run.
Serving Consumer	Retrieve available Recommendation Sets for a requested property/catalog boundary.	Cause results from another property or Catalog to be mixed into the response.
External Scheduler	Invoke the Training API at a chosen cadence.	Change recommendation semantics through scheduling.
Relational Data Source	Return configured canonical source rows.	Determine product intent or silently broaden the requested property boundary.

The APIs are internal and do not require authentication or authorization in this specification.

Canonical terms

The authoritative definitions are in CONTEXT.md. This specification relies particularly on Commerce Property, Tracking ID, Catalog ID, Product ID, Item, Training Run, Recommendation Snapshot, Recommendation Strategy, Fallback Strategy, and Recommendation Provenance.

Behavioral specification

Journeys and entry/exit conditions

Journey	Actor	Entry conditions	Trigger	Successful exit	Unsuccessful exit
JRN-1 Train recommendations	Training Caller	A saved data-source configuration and canonical property/catalog identity exist.	Submit a Training Run request and receive its identity.	The asynchronous run eventually makes a new versioned Recommendation Snapshot available.	Run failure is observable and the previously available snapshot remains unchanged.
JRN-2 Inspect training	Training Caller	A Training Run identity exists.	Request its status.	Current state and terminal outcome are returned.	An unknown identity is reported as absent.
JRN-3 Retrieve anchored recommendations	Serving Consumer	An available snapshot and anchor Item exist.	Request a strategy and anchor.	Ranked recommendations and provenance are returned from one snapshot.	Absence, invalid scope, or unavailable strategy is reported without synchronous training.
JRN-4 Retrieve property-wide recommendations	Serving Consumer	An available snapshot exists.	Request Best Sellers, Most Viewed, or Trending.	Ranked property/catalog-scoped recommendations are returned.	Absence or invalid scope is reported without fabricating behavioral evidence.

Training Run state model

requested --accepted--> pending
pending --execution starts--> running
running --all publication conditions satisfied--> succeeded / new snapshot becomes available
running --validation, streaming read, generation, or publication fails--> failed / current snapshot remains unchanged

Submission acknowledges the accepted request and returns its Training Run identity and initial state without waiting for a terminal outcome. At most one run is active for a data-source, Tracking ID, and Catalog ID boundary. A repeated submission with the same idempotency key returns the existing run; a different submission while that boundary is active reports the active run without creating another. V1 does not support cancellation. A new run may be submitted after the active run succeeds or fails.

Requirements

ID	Observable obligation	Upstream source	Verification class
REQ-001	The Training API SHALL accept Training Run requests only for a configured Commerce Property and Catalog boundary.	D-008, D-011, D-012	Contract test
REQ-002	A Training Run SHALL use a saved Data Source Adapter configuration and SHALL NOT accept arbitrary SQL or database credentials in the request.	D-009, D-010	Contract/security test
REQ-003	A Training Run SHALL filter canonical source rows by its configured Tracking ID and Catalog ID.	D-010 through D-012	Integration/property test
REQ-004	The service SHALL treat (data_source_id, TRACKING_ID) as Commerce Property identity and (data_source_id, TRACKING_ID, CATALOG_ID, PRODUCT_ID) as Item identity.	D-011	Property test
REQ-005	The service SHALL prohibit interaction evidence, candidates, anchors, and outputs from crossing Commerce Property or Catalog boundaries.	D-007, D-012	Invariant/property test
REQ-006	The service SHALL generate the registered Recommendation Strategies using their defined behavioral meanings.	D-003, D-006; category strategy request	Model behavior test
REQ-007	Frequently Bought Together SHALL use Order ID as its co-occurrence grouping key, and Also Viewed SHALL use Browsing Session ID as its co-occurrence grouping key.	D-003, D-013	Model behavior test
REQ-008	The service SHALL apply only the approved strategy-specific fallback hierarchy and SHALL disclose Recommendation Provenance for every served result.	D-004, D-007	Model behavior/contract test
REQ-009	A successful Training Run SHALL produce a versioned Recommendation Snapshot whose results and evaluation evidence share one source-data cutoff.	D-005, D-008	Integration/inspection
REQ-010	A failed Training Run SHALL NOT replace or partially alter the currently available Recommendation Snapshot.	D-008	Recovery test
REQ-011	The Serving API SHALL retrieve persisted Recommendation Sets without synchronously generating or retraining a strategy.	D-008	Contract/performance test
REQ-012	A served ranked entry SHALL disclose its Product ID, rank, score, confidence tier, and Recommendation Provenance, together with snapshot and data-cutoff identity.	D-004, D-005, D-008	Contract test
REQ-013	The service SHALL evaluate each property and strategy using temporal holdout Recall@K and NDCG@K plus the approved guardrails and baselines.	D-005	Measurement/inspection
REQ-014	A new database dialect SHALL be considered supported only after satisfying the same canonical streaming-read and isolation behaviors as existing adapters.	D-009, D-010, D-014	Compatibility suite
REQ-015	The Training API SHALL acknowledge an accepted request with a Training Run identity and initial state without waiting for generation to complete, and SHALL allow that run's current state and terminal outcome to be inspected separately.	DEC-2	Contract/state test
REQ-016	The Training API SHALL permit at most one active Training Run per data-source, Tracking ID, and Catalog ID boundary and SHALL apply the approved idempotency and conflict behavior to repeated submissions.	DEC-4	Contract/concurrency test
REQ-017	The Serving API SHALL distinguish a missing snapshot, a valid empty Recommendation Set, and a stale available snapshot using the approved observable responses.	DEC-5	Contract/state test
REQ-018	A Training Run SHALL publish one internally consistent Recommendation Snapshot only when every strategy either succeeds or reaches the approved valid insufficient_evidence outcome.	DEC-6	Integration/recovery test
REQ-019	The Serving API SHALL apply the approved result limit and deterministic ordering without recomputing recommendation scores.	DEC-7	Contract/ranking test
REQ-020	A Training Run request SHALL reference an externally provisioned stable data-source identity and SHALL report an absent or invalid configuration without accepting connection details or read mappings.	DEC-8	Contract/configuration test
REQ-021	A Training Run SHALL consume canonical source rows incrementally from the relational source and SHALL NOT extract, stage, or persist a raw interaction dataset.	D-014, DEC-9	Integration/inspection test
REQ-022	The service SHALL apply the approved snapshot, Training Run metadata, metric, and failed-run diagnostic retention periods, with deployment configuration permitted to override their default durations.	D-014, DEC-9	Lifecycle/configuration test
REQ-023	The V1 implementation SHALL successfully qualify a single Catalog containing at least 200,000 Products, 100 million view rows, 100 million purchase rows, and a historical window of at least two years while satisfying REQ-021.	D-015, DEC-10	Capacity qualification test
REQ-024	The V1 implementation SHALL satisfy the approved Training Run completion, API latency, and monthly availability objectives.	D-016, DEC-11	Performance/reliability test
REQ-025	A Training Run SHALL enforce its configured positive distinct-Product limits for co-occurrence groups, using defaults of 100 per Browsing Session and 200 per Order, preserve oversized-group rows for applicable popularity strategies, and report the exclusions in its metrics.	D-017, DEC-12	Configuration/model behavior/measurement test
REQ-026	A saved Data Source Adapter configuration SHALL require Online Purchase input and SHALL permit a merchandiser to omit Offline Purchase input; when Offline Purchases are configured, both channels SHALL contribute to purchase-driven strategies without combining Orders across channels solely because their Order IDs match.	D-018, DEC-13	Configuration/source-contract/integration test

Behavioral rules

ID	Parent	Rule
RULE-001	REQ-006	Frequently Bought Together uses same-Order evidence; Also Viewed uses same-session evidence; Similar Items uses Item Metadata; Best Sellers uses time-sensitive purchases; Most Viewed uses time-sensitive views; Trending uses recent momentum relative to a longer property baseline.
RULE-002	REQ-008	Also Viewed fallback order is supported co-view relationship, Item Metadata similarity, category-level recent views, then property-level recent views.
RULE-003	REQ-008	Frequently Bought Together fallback order is supported co-purchase relationship, category-pair co-purchase evidence, supplied compatibility/complement rules, category-level recent purchases, then property-level recent purchases.
RULE-004	REQ-008	Ordinary substitutable Item Metadata similarity SHALL NOT be represented as Frequently Bought Together evidence.
RULE-005	REQ-008	Similar Items may use Item Metadata when an Item is sparse or strictly cold.
RULE-006	REQ-010	Snapshot publication is all-or-nothing from the Serving Consumer's perspective.
RULE-007	REQ-012	No recommended Item may equal its anchor Item.
RULE-008	REQ-012	Unavailable or ineligible Catalog Items SHALL NOT be served when the source marks them as unavailable or ineligible at the snapshot cutoff.
RULE-009	REQ-017	Before any successful publication, retrieval reports snapshot_not_found; it does not return an invented empty snapshot.
RULE-010	REQ-017	When the selected snapshot exists but no eligible results exist for the requested anchor and strategy, retrieval returns an empty ranked list with reason insufficient_evidence and snapshot metadata.
RULE-011	REQ-017	A snapshot older than the property's configured freshness threshold remains serveable with is_stale: true, generation time, and data cutoff; the default threshold is 48 hours.
RULE-012	REQ-018	Missing required canonical fields, invalid property or Catalog boundaries, an incomplete streaming read, or a strategy computation error fails the entire Training Run.
RULE-013	REQ-018	Insufficient interaction volume may produce an empty strategy result marked insufficient_evidence without failing the Training Run.
RULE-014	REQ-018	A newly published snapshot SHALL NOT contain strategy results copied from an older snapshot.
RULE-015	REQ-019	limit accepts integer values from 1 through 100 and defaults to 20 when omitted.
RULE-016	REQ-019	Ranked results are ordered by descending score and then ascending Product ID for equal scores.
RULE-017	REQ-019	V1 returns one bounded ranked list and does not paginate Recommendation Sets.
RULE-018	REQ-022	By default, the five most recent successful Recommendation Snapshots per property/catalog are retained, while only the latest successful snapshot is served.
RULE-019	REQ-022	By default, Training Run metadata and metrics are retained for 90 days and failed-run diagnostics are retained for 30 days.
RULE-020	REQ-025	A Browsing Session containing at most the configured view_session_distinct_product_limit is eligible for Also Viewed co-occurrence; a Browsing Session above that limit is excluded whole from co-occurrence and category-pair evidence. The default limit is 100.
RULE-021	REQ-025	An Order containing at most the configured purchase_order_distinct_product_limit is eligible for Frequently Bought Together co-occurrence; an Order above that limit is excluded whole from co-occurrence and category-pair evidence. The default limit is 200.
RULE-022	REQ-025	Rows from an oversized group continue to contribute to Most Viewed, Best Sellers, and Trending as applicable, and Training Run metrics report excluded group and row counts separately for Browsing Sessions and Orders.
RULE-023	REQ-026	Absence of an Offline Purchase mapping does not fail configuration validation or a Training Run.
RULE-024	REQ-026	Online and Offline Purchase rows share canonical purchase fields and scoring semantics, but Purchase Channel is part of the internal Order grouping identity.
RULE-025	REQ-006	Popular Viewed Same Category and Popular Bought Same Category rank eligible Items in the anchor's known category by the corresponding decayed view or purchase popularity score.
RULE-026	REQ-006	Frequent Bought Different Category uses supported same-Order pairs whose known categories differ. Frequent Viewed Same Category and Frequent Viewed Different Category use supported same-session pairs whose known categories respectively match or differ.
RULE-027	REQ-006	Category-constrained lanes exclude missing categories, apply their relation before bounded candidate selection, and report insufficient evidence instead of using a fallback that violates the category or evidence rule.

Acceptance examples

EX-001 — Property and Catalog isolation

• Requirements/rules: REQ-003 through REQ-005
• Given: Two configured properties or Catalogs contain the same Product ID and have different interaction histories.
• When: A Training Run is requested for one property and Catalog.
• Then: Its snapshot contains only Items and evidence from that exact boundary.
• And not: No identifier, score, count, or relationship from the other boundary affects or appears in the result.
• Oracle source: D-007, D-011, D-012.

EX-002 — Same-Order relationship

• Requirements/rules: REQ-006, REQ-007, RULE-001
• Given: Products A and B occur in the same Order while A and C are purchased by the same property in different Orders.
• When: Frequently Bought Together evidence is generated for A.
• Then: The shared Order contributes co-occurrence evidence for B.
• And not: The separate Orders alone do not contribute same-Order evidence for C.
• Oracle source: D-003, D-013.

EX-003 — Strict cold Similar Items anchor

• Requirements/rules: REQ-008, RULE-005
• Given: An available Item has valid Item Metadata and no views or purchases.
• When: Similar Items is retrieved for that Item after a successful Training Run.
• Then: The service may return same-Catalog metadata-similar Items with cold-start provenance.
• And not: It does not claim co-view or co-purchase evidence.
• Oracle source: D-004, D-007.

EX-004 — FBT does not substitute metadata similarity

• Requirements/rules: REQ-008, RULE-003, RULE-004
• Given: A cold phone has metadata similarity to another phone but no co-purchase, complementary-category, or compatibility evidence.
• When: Frequently Bought Together is retrieved for the phone.
• Then: The ordinary similar phone is not represented as complementary evidence.
• And not: Metadata similarity is not labeled as Frequently Bought Together provenance.
• Oracle source: D-007.

EX-005 — Failed run preserves serving snapshot

• Requirements/rules: REQ-009 through REQ-011, RULE-006
• Given: Snapshot 7 is available and a later Training Run cannot read its configured data source completely.
• When: The later run terminates.
• Then: Its failed state and failure category are observable, and Snapshot 7 remains available unchanged.
• And not: No partial result from the failed run is served.
• Oracle source: D-008.

EX-006 — Serving does not train

• Requirements/rules: REQ-011
• Given: No available Recommendation Set exists for the requested boundary and strategy.
• When: A Serving Consumer requests recommendations.
• Then: The absence is reported according to the approved retrieval contract.
• And not: The request does not start a Training Run or query source interactions to calculate results.
• Oracle source: D-008, DEC-5.

EX-007 — Asynchronous Training Run submission

• Requirements/rules: REQ-015
• Given: A valid Training Run request and no conflicting run condition.
• When: A Training Caller submits the request.
• Then: The caller receives a stable Training Run identity and its initial non-terminal state without waiting for the streaming read or generation to finish.
• And: The run's later running, succeeded, or failed state can be inspected using that identity.
• And not: Disconnecting the submission request cancels the accepted Training Run.
• Oracle source: DEC-2.

EX-008 — Same-key repeated submission

• Requirements/rules: REQ-016
• Given: A non-terminal Training Run exists for a property/catalog boundary and idempotency key abc.
• When: The same boundary and idempotency key abc are submitted again.
• Then: The existing Training Run identity and current state are returned.
• And not: No second Training Run is created.
• Oracle source: DEC-4.

EX-009 — Conflicting concurrent submission

• Requirements/rules: REQ-016
• Given: A non-terminal Training Run exists for a property/catalog boundary.
• When: A different request is submitted for that same boundary.
• Then: The active Training Run is reported and the new request is not accepted as another run.
• And not: No queue entry or concurrent publisher is created.
• Oracle source: DEC-4.

EX-010 — No snapshot has ever succeeded

• Requirements/rules: REQ-017, RULE-009
• Given: No Training Run has successfully published a snapshot for the requested property/catalog boundary.
• When: A Serving Consumer requests any Recommendation Strategy.
• Then: The service reports snapshot_not_found.
• And not: It does not return an empty list that could be mistaken for evaluated evidence.
• Oracle source: DEC-5.

EX-011 — Valid empty Recommendation Set

• Requirements/rules: REQ-017, RULE-010
• Given: A snapshot exists but the requested anchor has no eligible recommendations after evidence and Catalog filtering.
• When: A Serving Consumer requests that anchor and strategy.
• Then: The service returns an empty ranked list, insufficient_evidence, and the snapshot identity and cutoff.
• And not: It does not start training or substitute an unapproved fallback.
• Oracle source: DEC-5.

EX-012 — Stale snapshot remains available

• Requirements/rules: REQ-017, RULE-011
• Given: The latest successful snapshot is older than the configured freshness threshold and a newer run has not succeeded.
• When: A Serving Consumer retrieves recommendations.
• Then: Results from that snapshot remain available with is_stale: true, generation time, and data cutoff.
• And not: Staleness is not hidden and the snapshot is not discarded solely because of age.
• Oracle source: DEC-5.

EX-013 — Insufficient evidence is publishable

• Requirements/rules: REQ-018, RULE-013
• Given: Canonical source data is valid, but no Order contains enough eligible co-purchase evidence for Frequently Bought Together.
• When: The Training Run completes all registered snapshot strategies.
• Then: The snapshot may publish with Frequently Bought Together marked insufficient_evidence and empty results.
• And not: The valid data-poor outcome is not reported as a computation failure.
• Oracle source: DEC-6.

EX-014 — One strategy computation fails

• Requirements/rules: REQ-010, REQ-018, RULE-012, RULE-014
• Given: A current snapshot exists and one strategy in a later Training Run terminates with a computation error.
• When: Publication is evaluated.
• Then: The Training Run fails and the current snapshot remains unchanged.
• And not: No successful new strategy is published and no old strategy is copied into a mixed snapshot.
• Oracle source: DEC-6.

EX-015 — Default result count and stable ties

• Requirements/rules: REQ-019, RULE-015 through RULE-017
• Given: A Recommendation Set contains more than 20 eligible entries and Products B and A have the same score.
• When: A Serving Consumer omits limit.
• Then: At most 20 entries are returned, with higher scores first and Product A before Product B when both are included.
• And not: No continuation token is returned and no serving-time rescoring occurs.
• Oracle source: DEC-7.

EX-016 — Invalid result limit

• Requirements/rules: REQ-019, RULE-015
• Given: An available Recommendation Set exists.
• When: A Serving Consumer requests limit 0 or 101.
• Then: The request is rejected as an invalid limit.
• And not: The value is not silently clamped.
• Oracle source: DEC-7.

EX-017 — Unknown data-source configuration

• Requirements/rules: REQ-002, REQ-020
• Given: No deployment configuration exists for data-source identity missing.
• When: A Training Caller submits a run referencing missing.
• Then: The request reports that the configured source is absent and no Training Run is accepted.
• And not: The caller is not invited to provide a connection URL, credentials, or SQL in the request.
• Oracle source: DEC-8.

EX-018 — Source rows are streamed without raw-data staging

• Requirements/rules: REQ-021
• Given: A valid Training Run reads a large set of canonical view and purchase rows from its configured relational source.
• When: The source returns rows incrementally.
• Then: The Training Run consumes those rows incrementally for validation and recommendation generation.
• And not: It does not first copy the source rows into a Parquet file, staging table, object store, or other persisted raw interaction dataset.
• Oracle source: D-014, DEC-9.

EX-019 — Default retention lifecycle

• Requirements/rules: REQ-022, RULE-018, RULE-019
• Given: A property/catalog has six successful snapshots and run records older than the configured retention periods.
• When: Retention is applied using the default configuration.
• Then: The latest five successful snapshots remain retained, only the newest is eligible for serving, Training Run metadata and metrics remain for 90 days, and failed-run diagnostics remain for 30 days.
• And not: No raw source interaction rows are retained by the service.
• Oracle source: D-014, DEC-9.

EX-020 — Minimum capacity qualification

• Requirements/rules: REQ-021, REQ-023
• Given: A configured Catalog contains at least 200,000 Products, 100 million view rows, 100 million purchase rows, and two years of historical interactions.
• When: The V1 capacity qualification Training Run processes that Catalog.
• Then: The run completes successfully using direct streaming reads and produces or validly reports all registered strategies according to their evidence outcomes.
• And not: The qualification does not stage raw source rows or treat the qualification volumes as hard product limits.
• Oracle source: D-015, DEC-10.

EX-021 — Service-level qualification

• Requirements/rules: REQ-023, REQ-024
• Given: Production-equivalent resources and the approved minimum capacity qualification profile.
• When: End-to-end Training Runs and representative API workloads are measured.
• Then: Training completes within 12 hours; Training submission and status latency is at most 500 ms at p95; Serving latency is at most 90 ms at p95 and 150 ms at p99; monthly Serving availability is at least 99.9%; and monthly Training API availability is at least 99.5%.
• And not: Source-read time, failed requests, or unavailable periods are silently removed from the applicable measurement population merely to satisfy an objective.
• Oracle source: D-016, DEC-11.

EX-022 — Group at the inclusive limit contributes pairs

• Requirements/rules: REQ-025, RULE-020, RULE-021
• Given: The default group-limit configuration, one Browsing Session containing exactly 100 distinct Products, and one Order containing exactly 200 distinct Products.
• When: The Training Run generates Also Viewed and Frequently Bought Together evidence.
• Then: Both groups remain eligible to contribute their applicable co-occurrence and category-pair evidence.
• And not: Neither group is excluded merely for being equal to its limit.
• Oracle source: D-017, DEC-12.

EX-023 — Oversized groups are excluded without losing popularity evidence

• Requirements/rules: REQ-025, RULE-020 through RULE-022
• Given: The default group-limit configuration, one Browsing Session containing 101 distinct Products, and one Order containing 201 distinct Products.
• When: A Training Run processes their rows.
• Then: Neither group contributes any co-occurrence or category-pair evidence; their view and purchase rows still contribute to applicable popularity and Trending strategies; and the run metrics report both excluded groups and their affected row counts.
• And not: The service does not truncate, sample, or partially pair either oversized group.
• Oracle source: D-017, DEC-12.

EX-024 — Offline purchases are optional and channel-scoped

• Requirements/rules: REQ-026, RULE-023, RULE-024
• Given: One merchandiser configures Online Purchases only, while another configures Online and Offline Purchases containing the same source Order ID.
• When: Each property completes a Training Run.
• Then: The online-only run succeeds, and the second run uses valid purchases from both channels for purchase-driven strategies.
• And not: The absent Offline Purchase mapping does not fail the first run, and matching cross-channel Order IDs do not create one combined Order or false co-purchase pairs in the second run.
• Oracle source: D-018, DEC-13.

Quality and external boundaries

Quality attributes

ID	Parent	Attribute	Obligation	Measurement context
NFR-001	REQ-005	Isolation	Zero cross-property and cross-Catalog records or influence in generated and served results.	Adversarial multi-property compatibility suite.
NFR-002	REQ-010	Reliability	A failed run causes zero observable mutation to the currently available snapshot.	Failure injection at streaming-read, generation, evaluation, and publication boundaries.
NFR-003	REQ-009	Reproducibility	Identical canonical inputs, cutoff, configuration, and product version produce equivalent ranked outputs and metrics.	Repeat-run comparison, allowing only explicitly documented deterministic tie handling.
NFR-004	REQ-014	Compatibility	PostgreSQL, SQLite, Snowflake, or any additional dialect passes one shared canonical adapter contract before being declared supported.	Dialect compatibility suite against representative fixtures.
NFR-005	REQ-013	Evaluation integrity	Warm, sparse, strict-cold, and Cold Commerce Property conditions are reported separately when present rather than hidden in one aggregate.	Evaluation-report inspection.
NFR-006	REQ-023	Capacity	A single-Catalog qualification run supports at least 200,000 Products, 100 million view rows, 100 million purchase rows, and two years of history.	Representative end-to-end benchmark using streaming source reads and production-equivalent resource limits.
NFR-007	REQ-024	Batch completion	A valid Training Run at or below the qualification profile reaches a terminal outcome within 12 hours of acceptance.	Production-equivalent qualification runs, including source-read time.
NFR-008	REQ-024	API latency	Training submission and status responses have p95 latency at most 500 ms; Serving responses have p95 latency at most 90 ms and p99 latency at most 150 ms.	Successful and product-defined error responses measured at the service boundary over a representative rolling window, excluding only caller cancellation.
NFR-009	REQ-024	Availability	Serving API monthly availability is at least 99.9%, and Training API monthly availability is at least 99.5%.	Calendar-month service-boundary measurement, excluding only predeclared maintenance if the deployment's availability policy permits it.

The capacity values above are qualification floors rather than hard product limits.

Data and privacy

• Behavioral records may be used only inside their configured Commerce Property and Catalog boundary to preserve recommendation correctness.
• The service reads source commerce data for recommendation generation and evaluation; it does not modify source tables.
• Canonical source rows are consumed as a stream and are never retained as an extracted or staged raw interaction dataset.
• By default, the service retains five successful snapshots per property/catalog, Training Run metadata and metrics for 90 days, and failed-run diagnostics for 30 days; deployment configuration may override these values.
• Recommendation Snapshots must not expose source connection details, raw interaction rows, Order IDs, or Session IDs through the Serving API.

External systems and failure behavior

Boundary	Observable contract	Failure behavior	Recovery/idempotency	Compatibility
Training Caller	Submit and separately inspect an asynchronous property/catalog Training Run.	Invalid requests are rejected; a conflicting active-boundary request reports the active run without changing a snapshot.	Same-key repetition returns the existing run; a new run is permitted after success or failure; cancellation is unavailable.	Versioned API contract required.
Relational Data Source	Stream canonical rows through a saved adapter configuration.	Streaming-read or validation failure fails the run and preserves the current snapshot.	A new Training Run may be requested after correction; automatic retry policy is open.	Adapter contract is engine-neutral.
Serving Consumer	Retrieve one available snapshot's ranked results.	Missing snapshots, valid empty results, and stale snapshots follow DEC-5.	Retrieval is read-only.	Versioned API contract required.

Audit and observability

• Each Training Run must expose property/catalog scope, requested time, state transitions, data cutoff, configuration identity, product version, terminal outcome, and snapshot identity when successful.
• Each Training Run must expose oversized Browsing Session and Order exclusion counts, including both group counts and affected row counts.
• Audit information must not include source credentials or raw behavioral records.
• Each served response must identify the Recommendation Snapshot and data cutoff used.

Dependencies and risks

ID	Type	Statement	Response
DEP-001	Dependency	Source mappings must provide canonical identity, timestamp, Order ID, and Session ID semantics.	Reject invalid affected training behavior rather than infer a different meaning.
DEP-002	Dependency	Catalog availability and eligibility must be available to enforce serving filters.	Resolve required catalog fields before approval.
RISK-001	Risk	A misconfigured source read could cross property boundaries.	Bind Tracking ID and Catalog ID, validate streamed rows, and run isolation tests.
RISK-002	Risk	Metadata fallback may dominate behavioral evidence or distort complementary intent.	Report provenance and support cohorts; benchmark fallback tiers separately.
RISK-003	Risk	Database neutrality may hide dialect-specific consistency or timestamp semantics.	Shared compatibility contract and explicit cutoff semantics per adapter.

Additive geographic and Swimlane contract

The five anchored category strategies are popular-viewed-same-category, popular-bought-same-category, frequent-bought-different-category, frequent-viewed-same-category, and frequent-viewed-different-category. “Popular” ranks eligible Items by the corresponding decayed event signal within the anchor's known category. “Frequent” ranks supported co-context neighbors, restricting to the named known-category relation before result truncation. The additional recommendations-using-recently-viewed and recommendations-using-recently-bought strategies use separately authorized, bounded recent Shopper histories as seeds into published co-view and co-purchase neighborhoods. They do not read raw interactions during serving.

Online source queries obtain country, region, and city from the visit's geo_location_id and its geo_location row; offline purchase queries use the location supplied with the transaction. A browsing session or purchase order contributes to its city, enclosing region, country, and global aggregates only under one consistent complete path. Missing geography contributes globally only. Country/region/city names are normalized and scoped to the Commerce Property and Catalog rather than assumed to be universal city identifiers. Local candidates require support from at least ten distinct qualifying contexts, and exact local support and scores are not returned by the contextual API.

A configured Swimlane has a Commerce Scope, name, ordered list of strategy/geography steps, and quota from 1 to 100 (default 50). Each step appends eligible, nonduplicate Items in its own ranking order until the quota is filled; the next step is tried only for remaining slots. Steps may explicitly exclude recently purchased Items; no blanket exclusion applies. After every step, an authorized Shopper's eligible, newest-first browsing history fills any remaining slots. Without authorized history, the response may be shorter than its quota. Every result identifies its actual strategy, geographic level, and step.

POST /v1/catalogs/{catalog_id}/swimlanes/{swimlane_name}:resolve is a read-only contextual endpoint. A property bearer authenticates before body parsing and determines the Data Source and Tracking ID; the body may supply an anchor Item, userContext.city/region/country, and a quota override within the configured bound. A signed Shopper context is required only to access recent-history steps or the terminal history filler. All variations in one response come from one published Snapshot. The response is private and noncacheable. Existing GET routes and their default global serving behavior remain unchanged.

Open questions

None. All authoring decisions required for Sponsor review are resolved.

Governance and traceability

Artifact governance

• Strategic source: PRODUCT_VISION_STRATEGY.md, approved revision 0.16.
• Feature specification: This file, revision 0.15; the V1 baseline was approved by the Sponsor on 2026-08-05 and the additive Swimlane behavior was directed by the Sponsor on 2026-09-23.
• Authority model: Spec-anchored.
• Persistence model: Living; material intent changes update this specification first and require Sponsor reapproval plus downstream impact analysis.
• Intent-change authority: Sponsor.
• Change protocol: Increment the revision, return to READY FOR REVIEW, reconcile affected designs/contracts/tests/code, and rerun applicable evidence before approval.

Forward traceability

Strategic source	Requirements	Rules/NFR	Examples	Downstream design	Status
D-002 through D-007	REQ-005 through REQ-008, REQ-013	RULE-001 through RULE-005, NFR-001, NFR-005	EX-001 through EX-004	Design revision 0.2, approved	covered
D-008, DEC-2, DEC-4, DEC-5, DEC-6, DEC-7	REQ-001, REQ-009 through REQ-012, REQ-015 through REQ-019	RULE-006, RULE-009 through RULE-017, NFR-002, NFR-003	EX-005 through EX-016	Design revision 0.2, approved	covered
D-009, D-010, D-014, DEC-8, DEC-9	REQ-002, REQ-003, REQ-014, REQ-020 through REQ-022	RULE-018, RULE-019, NFR-004	EX-001, EX-005, EX-017 through EX-019	Design revision 0.2, approved	covered
D-011 through D-013	REQ-003 through REQ-007	NFR-001	EX-001, EX-002	Design revision 0.2, approved	covered
D-015, DEC-10	REQ-023	NFR-006	EX-020	Design revision 0.2, approved	covered
D-016, DEC-11	REQ-024	NFR-007 through NFR-009	EX-021	Design revision 0.2, approved	covered
D-017, DEC-12	REQ-025	RULE-020 through RULE-022	EX-022, EX-023	Design revision 0.2, approved	covered
D-018, DEC-13	REQ-026	RULE-023, RULE-024	EX-024	Design revision 0.2, approved	covered

Backward traceability

• All approved strategic decisions have forward and backward specification traceability.
• No architecture, storage technology, framework, endpoint path, or physical schema is authorized by this specification.

Author quality gate

• [x] Exact upstream source, revision, and approval state are recorded.
• [x] Scope, non-goals, canonical language, current baseline, strategic trace, and approved behaviors are explicit.
• [x] Requirements and examples are traceable and implementation-independent.
• [x] Property and Catalog isolation is measurable.
• [x] Observable asynchronous API lifecycle and internal-access posture are complete.
• [x] Partial failure, absence, concurrency, streaming-read, and retention behavior are resolved.
• [x] Minimum capacity qualification thresholds are resolved.
• [x] Training completion, API latency, and availability thresholds are resolved.
• [x] Sponsor review and approval are complete, including optional Offline Purchases; Engineering and Quality remain required downstream design and verification participants.

Author verdict: APPROVED

Next human decision: Review the additive geographic Swimlane contract before production release.

Approved baseline: Revision 0.13, approved by Sponsor (user) on 2026-08-05; revision 0.15 records the subsequent Sponsor-directed extension.