Problem
The storyboard compliance suite can pass all tracks while filter parameters on delivery endpoints are completely ignored. An endpoint can accept start_date/end_date, return a correctly-shaped response, pass all compliance checks — and silently return the same data regardless of what dates were passed.
This is the same class of bug as a search endpoint that accepts a query param but returns the full unfiltered list. The schema is valid. The contract is broken.
What the storyboard currently checks
| Check |
Status |
reporting_period exists |
✅ |
reporting_period has start + end |
✅ |
| Response fields match schema |
✅ |
What it does not check
| Check |
Status |
Does passing start_date=X return data scoped to X? |
❌ |
Does reporting_period.start reflect the input date? |
❌ |
| Do two calls with different date ranges return different results? |
❌ |
Why this is a reference architecture gap, not just an implementation bug
The natural development loop for a seller agent is:
- Implement endpoint to return the right shape
- Run storyboard → green
- Ship
There is no step that catches "filtering doesn't actually work." The compliance suite optimises for discoverability of missing fields and wrong types, but gives no signal on whether input parameters affect output.
Any implementer following the reference architecture in good faith can ship silently broken filtering without ever seeing a test failure.
The spec gap
The spec defines start_date/end_date semantics clearly — inclusive/exclusive bounds, what reporting_period should reflect — but is silent on whether implementations MUST honour those inputs. The normative statement:
"Implementations MUST scope results to the provided filter. Returning unfiltered results when a filter is supplied is a protocol violation."
does not appear anywhere. The contract is documented but not required.
Affected surface
This applies specifically to endpoints where filter correctness is objectively verifiable — same underlying data, different filter input, must produce different output:
get_media_buy_delivery — start_date, end_dateget_media_buys — status_filter, media_buy_idslist_creatives — status, media_buy_id
Note: get_products with brief/filters is intentionally out of scope. Brief interpretation is seller-differentiated — a seller returning "too many" products for a vague brief is a relevance question evaluated by the buyer agent, not a protocol violation. Including it would invite debate that dilutes the delivery-filter issue where the contract is clear and verifiable.
Proposed fix
1. Add behavioural test scenarios to the storyboard
For each affected endpoint, the storyboard should include a scenario that verifies the filter actually affects the response. Using the test controller to seed two distinct data states:
given: delivery data exists for media buy X on 2026-04-15
and: delivery data exists for media buy X on 2026-04-01
when: get_media_buy_delivery called with start_date=2026-04-15, end_date=2026-04-16
then: reporting_period.start = 2026-04-15T00:00:00Z
and: response differs from a call with start_date=2026-04-01, end_date=2026-04-02
Pre-requisite: This requires the storyboard runner to support stateful seeding — two distinct data states set up in sequence before assertions run. If simulate_delivery in the test controller doesn't currently support this, that capability needs to land before the behavioural assertions can be written. Scoping this fix without addressing the seeding dependency will result in a half-complete implementation.
2. Add normative language to the spec
For delivery and reporting endpoints, the spec should state explicitly that filter parameters MUST have observable effect on the response. This closes the gap between "the contract is documented" and "the contract is required."
Affected spec files
docs/media-buy/task-reference/get_media_buy_delivery.mdxdocs/media-buy/task-reference/get_media_buys.mdx- Storyboard definitions for the
reporting compliance track
Impact
Without this, sellers can pass compliance certification with filtering silently broken. Buyers relying on date-scoped delivery polling will receive cumulative data instead of per-period data, making daily reporting unreliable. The bug is invisible until someone manually compares responses across multiple calls with different inputs — it won't surface in any automated compliance check.
Problem
The storyboard compliance suite can pass all tracks while filter parameters on delivery endpoints are completely ignored. An endpoint can accept
start_date/end_date, return a correctly-shaped response, pass all compliance checks — and silently return the same data regardless of what dates were passed.This is the same class of bug as a search endpoint that accepts a query param but returns the full unfiltered list. The schema is valid. The contract is broken.
What the storyboard currently checks
reporting_periodexistsreporting_periodhasstart+endWhat it does not check
start_date=Xreturn data scoped to X?reporting_period.startreflect the input date?Why this is a reference architecture gap, not just an implementation bug
The natural development loop for a seller agent is:
There is no step that catches "filtering doesn't actually work." The compliance suite optimises for discoverability of missing fields and wrong types, but gives no signal on whether input parameters affect output.
Any implementer following the reference architecture in good faith can ship silently broken filtering without ever seeing a test failure.
The spec gap
The spec defines
start_date/end_datesemantics clearly — inclusive/exclusive bounds, whatreporting_periodshould reflect — but is silent on whether implementations MUST honour those inputs. The normative statement:does not appear anywhere. The contract is documented but not required.
Affected surface
This applies specifically to endpoints where filter correctness is objectively verifiable — same underlying data, different filter input, must produce different output:
get_media_buy_delivery—start_date,end_dateget_media_buys—status_filter,media_buy_idslist_creatives—status,media_buy_idNote:
get_productswithbrief/filtersis intentionally out of scope. Brief interpretation is seller-differentiated — a seller returning "too many" products for a vague brief is a relevance question evaluated by the buyer agent, not a protocol violation. Including it would invite debate that dilutes the delivery-filter issue where the contract is clear and verifiable.Proposed fix
1. Add behavioural test scenarios to the storyboard
For each affected endpoint, the storyboard should include a scenario that verifies the filter actually affects the response. Using the test controller to seed two distinct data states:
Pre-requisite: This requires the storyboard runner to support stateful seeding — two distinct data states set up in sequence before assertions run. If
simulate_deliveryin the test controller doesn't currently support this, that capability needs to land before the behavioural assertions can be written. Scoping this fix without addressing the seeding dependency will result in a half-complete implementation.2. Add normative language to the spec
For delivery and reporting endpoints, the spec should state explicitly that filter parameters MUST have observable effect on the response. This closes the gap between "the contract is documented" and "the contract is required."
Affected spec files
docs/media-buy/task-reference/get_media_buy_delivery.mdxdocs/media-buy/task-reference/get_media_buys.mdxreportingcompliance trackImpact
Without this, sellers can pass compliance certification with filtering silently broken. Buyers relying on date-scoped delivery polling will receive cumulative data instead of per-period data, making daily reporting unreliable. The bug is invisible until someone manually compares responses across multiple calls with different inputs — it won't surface in any automated compliance check.