Server-side ad templates design spec

[jevansnyc]

Summary

• Adds design spec for server-side ad templates, replacing client-side SDK slot discovery (Prebid.js, Smart Slots) with edge-configured creative opportunities
• TS matches URL patterns to pre-configured slot templates, fires the full auction (PBS + APS + all providers) at request receipt in parallel with origin fetch, and injects winning bids into head before the browser receives HTML
• Estimated ~2,000ms improvement in time-to-ad-visible (from ~3,200ms to ~1,200ms)

Test plan

• Review spec for accuracy against current auction pipeline
• Validate creative-opportunities.toml schema covers publisher slot inventory
• Confirm open questions with publisher (URL patterns, homepage slot count, PBS stored request setup)

[prk-Jr]

On review against the current codebase, 8 design questions need answers before implementation planning can begin. 7 are inline below; one cross-cutting question (win notifications) is here:

---

❓ Win notifications (nurl/burl): fire server-side or defer?

When GAM renders the creative, TS is out of the render path. The nurl/burl fields from PBS/APS responses are known to TS at auction time but have no path to the client or to a server-side firing mechanism. SSP win counting breaks silently for server-auctioned impressions. Should TS fire nurl as a background HTTP request at bid-selection time, or is this explicitly deferred to a later phase?

[prk-Jr]

❓ /auction POST role after this ships

This goal says "return pre-collected winning bids to the browser's lightweight /auction POST." Sections 4.4 and 4.5 say "no /auction POST needed — bids are already in the page." These are contradictory. The JS client currently always POSTs to /auction. Definitive answer needed: does __ts_bids replace the POST entirely, or does /auction remain as a fallback for URLs that don't match any slot template?

[jevansnyc]

Good catch. _ts_bids replaces the POST for URLs that match templates. /auction also stays as the fallback path for URLs without matching templates (preserves backward compatability for non-templated pages and for publishers who haven't adopted creative-opportunities.toml yet)

[prk-Jr]

❓ creative-opportunities.toml: compile-time include_str!() or Fastly KV at runtime?

include_str!() bakes the file into the WASM binary — every slot config change requires a full rebuild + Fastly deploy (~15 min). The phrase "ad ops can edit this file independently" (line 71) does not hold under that model. The RuntimeServices abstraction already exposes services.kv_store(). Which model is intended: compile-time (fast reads, deploy required per change) or runtime KV (live edits, no rebuild)?

[jevansnyc]

Fastly deploy's don't take 15 minutes first of all. That said, lets reduce dependence on KV store where we can for timing and publisher cost perspective and keep it simple in the WASM binary with include_str!()

[prk-Jr]

❓ APS in Phase 1: included or excluded, and param source

APS bidder params currently flow from the browser's AdRequest POST — there is no client for a server-triggered auction. creative-opportunities.toml has no [slot.providers.aps] section and APS does not use PBS stored requests. Is APS in scope for Phase 1? If yes, where do per-slot APS params come from?

[jevansnyc]

Yes, APS in scope. Lets add them as [slot.provider.aps] in the toml. They should complete with all the other demand unless you see something i don't?

[prk-Jr]

❓ hb_pb price bucketing: granularity table and full key set

hb_pb is a Prebid price bucket string (discretized CPM bin), not a raw price. No bucketing logic exists in the codebase — this is a net-new component. Which granularity table: low / medium / high / auto / dense / custom? Is it per-publisher configurable? And what is the complete __ts_bids key set — just hb_pb, hb_bidder, hb_adid, or also hb_size, hb_deal, hb_format?

[jevansnyc]

Lets make "dense" the default with a publisher override on the granularity setting. Keep the key set as is to match GAM standard.

[prk-Jr]

❓ slot.id as GPT adUnitPath

GPT's defineSlot(adUnitPath, size, optDiv) first argument must be the full GAM network path (e.g., /21765378893/homepage-banner). Using a short key like atf_sidebar_ad silently produces a non-functional slot — GAM will not serve to it. Is slot.id the full GAM path, or does creative-opportunities.toml need a separate field (e.g., gam_unit_path)?

[jevansnyc]

You're correct. We should add an optional gam_unit_path field per slot, plus a top-level gam_network_id config. Default behavior: gam_unit_path = "/{network_id}/{slot.id}". Publishers can override per-slot for non-standard paths.

[prk-Jr]

❓ Streaming mode </head> boundary: Phase 1 or deferred?

The current streaming pipeline (merged in #562) buffers until end-of-document when post-processors run. "Buffer only until </head>, inject bids, then resume streaming immediately" is a new mode not currently implemented — it requires new infrastructure in the HTML processor. Is this required for Phase 1 launch, or is injecting at document end acceptable as an initial release?

[prk-Jr]

❓ Auction timeout: new config key or reuse existing? (Section 9, Q4)

The spec recommends 500ms for server-triggered auctions vs the current 1,000ms client-side budget. There are currently three overlapping timeout values: [auction].timeout_ms, [integrations.prebid].timeout_ms, [integrations.aps].timeout_ms. Does the server-triggered path get a new dedicated key (e.g., [creative_opportunities].auction_timeout_ms) or does it override an existing one?

[jevansnyc]

Lets use an optional dedicated key with fallback that makes sense:

[creative_opportunities]
"# Optional. Defaults to [auction].timeout_ms if not set.
"# Recommended: 500ms (vs client-side 1000-1500ms) due to lower edge→PBS RTT.
auction_timeout_ms = 500"

• Optional + fallback keeps it backward compatible. Publishers not setting it inherit [auction].timeout_ms
• Per-provider config should stay untouched. [integrations.prebid].timeout_ms and [integrations.aps].timeout_ms continue to define provider-level ceilings ... the orchestrator's existing min(remaining_global_budget, provider_timeout) enforcement applies as today.
• Single source of truth for 4.6 streaming. A_deadline (the buffer deadline) = T₀ + creative_opportunities.auction_timeout_ms (or fallback). The same value gates both the auction and the head-boundary buffer hold ... they're the same deadline.

[jevansnyc]

On review against the current codebase, 8 design questions need answers before implementation planning can begin. 7 are inline below; one cross-cutting question (win notifications) is here:

❓ Win notifications (nurl/burl): fire server-side or defer?

When GAM renders the creative, TS is out of the render path. The nurl/burl fields from PBS/APS responses are known to TS at auction time but have no path to the client or to a server-side firing mechanism. SSP win counting breaks silently for server-auctioned impressions. Should TS fire nurl as a background HTTP request at bid-selection time, or is this explicitly deferred to a later phase?

Yes, lets split the calls by where the truth lives:

nurl: TS orchestrator fires fire-and-forget BG HTTP req from the edge at bid-selection time. Edge→SSP RTT ~20–30ms, no auction-path latency cost. Per-provider switch (e.g., [integrations.prebid].fire_nurl_at_edge, default true) for cases where PBS deployment already handles win events and we'd otherwise double-fire. APS handled per its own notification spec.

burl: Fired client-side when the ad actually renders, using the existing GPT slotRenderEnded event. Logic lives inside the tsjs bundle (__tsAdInit registers the listener after defining slots). On render: if !event.isEmpty AND event.slot.getTargeting('hb_adid')[0] === bidData.hb_adid, fire ... this confirms both render and that our specific Prebid bid (not a direct deal or backfill) won the GAM line item match. TS embeds burl per slot in __ts_bids so the client has it without a round-trip.

[aram356]

Summary

Design spec for server-side ad templates. The diagnosis (browser is the slowest place to run an auction; edge→PBS RTT is much shorter; slot inventory is URL-derivable) is sound, but the spec materially understates the architectural lift and skips several correctness concerns. Cross-referenced against auction/orchestrator.rs, auction/types.rs, auction/endpoints.rs, integrations/registry.rs, integrations/prebid.rs, html_processor.rs, streaming_processor.rs, and publisher.rs.

Blocking

🔧 wrench

• CI is red on this file: cd docs && npx prettier --check superpowers/specs/2026-04-15-server-side-ad-templates-design.md fails (format-docs job). Fix: cd docs && npm run format:write and commit.
• Cache contract missing for __ts_bids — see inline.
• Consent / GDPR flow missing for the new trigger — see inline.
• IntegrationHeadInjector is sync; spec assumes async wait — see inline.
• "Auction in parallel with origin" incompatible with current sync handle_publisher_request — see inline.
• Schema mismatch with AdFormat (missing media_type) — see inline.
• Glob example is wrong against standard glob libraries — see inline.
• Untrusted bid strings injected as inline JSON without escape contract (XSS) — see inline.
• include_str!() contradicts "ad ops can edit independently" — see inline.
• APS bidder isn't keyed by PBS stored requests — see inline.
• Spec references the wrong timeout config key — see inline.

❓ question

• Kill-switch / rollback when config is empty or absent? — see inline.
• Who fires nurl/burl; what replaces Prebid analytics adapters? — see inline.

Non-blocking

🤔 thinking

• Latency numbers are modeled, not measured — see inline.
• Pattern-matching cost is O(slots × patterns) — see inline.
• No telemetry contract for the new trigger — see inline.

♻️ refactor

• Validate slot IDs at startup (XSS + cross-reference safety) — see inline.
• googletag.defineSlot(slot.id, ..., slot.id) is wrong (ad-unit path ≠ div ID) — see inline.
• __ts_ad_slots belongs in a dedicated head injector, not prebid.rs — see inline.

🌱 seedling

• Plan for Edge Dictionary / KV-backed config swap — see inline.
• Sketch the Phase 2 server-side-GAM approach — see inline.

📌 out of scope

• Browser integration test coverage: the existing browser-integration tests today exercise the client-side ad pipeline. Implementation PRs need parallel coverage — a fixture page with creative-opportunities.toml matched, a stubbed PBS, and asserts that __ts_bids lands and googletag.setTargeting is invoked. Worth flagging now so it lands with the implementation, not after.

⛏ nitpick

• Italics convention around the date — see inline.

CI Status

• format-docs: FAIL (prettier delta on this file; 45+/32− to fix)
• cargo fmt: PASS
• cargo clippy: PASS
• cargo test: PASS
• vitest: PASS
• browser/integration tests: PASS
• CodeQL / Analyze (rust, javascript-typescript, actions): PASS

[aram356]

🔧 wrench — Per-request bid injection without a cache contract is unsafe.

__ts_bids is per-request, per-user data injected into a publisher HTML body that flows through Fastly. The spec never states the cache contract. If the response is cacheable (default for HTML on Compute unless explicitly suppressed), bids leak across users.

Fix: Add a section that mandates Cache-Control: private, no-store (or equivalent surrogate-control + cache-key segmentation) on any response with __ts_bids injected, and explain what happens when the publisher origin sends conflicting cache headers. This is a P0 omission — the entire design rests on it.

[aram356]

🔧 wrench — Consent / GDPR flow is missing for the new auction trigger.

Today's /auction handler in auction/endpoints.rs:66-77 builds a ConsentContext (TCF, GPP, US Privacy, GPC) before running an auction. The spec triggers the auction at request receipt — before the page's consent UI (Didomi) can update preferences — and never describes how consent is propagated, suppressed, or reconciled.

Required additions:

• Explicit consent-gating decision (when auction is suppressed entirely)
• Handling of mid-page consent revocation when bids are already in <head>
• EC-ID / cookie behavior at the new trigger
• Treatment in §8 Edge Cases as a first-class "no consent" case

Without this the design is a regulatory regression.

[aram356]

🔧 wrench — IntegrationHeadInjector is synchronous; spec assumes it can wait on async results.

The current trait at integrations/registry.rs:392-397 is fn head_inserts(&self, ctx: &IntegrationHtmlContext<'_>) -> Vec<String> and runs inside a lol_html element callback (html_processor.rs:236-267) — fully sync, no .await.

Pick one approach and document it:

1. Run the auction before building the HtmlProcessorConfig and pass pre-resolved bids in (simpler — but means buffering origin until auction completes), or
2. Introduce a new async/late-injection mechanism plus a chunk-holding state machine in the streaming pipeline (which today has no "hold and wait" primitive — see html_processor.rs:46-128).

Also note lol_html element!("head", ...) fires on the opening tag; "before </head>" requires el.on_end_tag(). Spec must call this out and pick an approach.

[aram356]

🔧 wrench — "Auction in parallel with origin fetch" is incompatible with the current publisher path.

publisher.rs:527 calls req.send(&backend_name) synchronously inside a non-async handle_publisher_request. Real concurrency requires send_async + a select (or join) between the orchestrator future and the pending origin request, and propagating async up through publisher handling.

Spec §3 lists "no orchestrator changes" and §7 lists this as a one-line "Request handler modification" — the actual lift is a meaningful restructuring of the publisher request path. List it explicitly in §7 as a multi-step migration including the async propagation.

[aram356]

🔧 wrench — Schema mismatch: formats = [{ width, height }] won't deserialize into AdFormat.

auction/types.rs:47-52 defines AdFormat { media_type: MediaType, width: u32, height: u32 } — media_type is required and MediaType has no default. The TOML examples and Rust struct in §4.1 omit media_type.

Fix: Either change the schema/struct to include media_type (or default to Banner via #[serde(default)]), or define a separate CreativeOpportunityFormat plus an explicit converter to AdFormat.

[aram356]

♻️ refactor — googletag.defineSlot(slot.id, ..., slot.id) is wrong.

defineSlot(adUnitPath, sizes, divId) — adUnitPath is the GAM ad-unit path (e.g., /12345/network/article-atf) and divId is the page DOM container ID. Reusing slot.id for both will break GAM trafficking.

Fix: Add separate gam_ad_unit_path and div_id fields to the slot config.

[aram356]

♻️ refactor — __ts_ad_slots belongs in a dedicated head injector, not stuffed into prebid.rs.

The §7 plan modifies integrations/prebid.rs to emit __ts_ad_slots. But the spec also says "Prebid.js is eliminated." Prebid integration shouldn't own the new GPT-facing global.

Fix: Put the head injection in a new creative_opportunities integration (or extend the existing gpt integration at integrations/gpt.rs) and decouple it from prebid.

[aram356]

🌱 seedling — Plan for Edge Dictionary / KV-backed config swap.

Even if Phase 1 ships with include_str!(), sketch the migration path to dictionary/KV-backed config (read at request time, hot-reload, validation contract). Prevents painting yourselves into a corner when ad ops actually does want to make changes between deploys.

[aram356]

🌱 seedling — Server-side GAM is the real win.

Phase 1 keeps GAM in the browser, capping the savings ceiling. Briefly outline the Phase 2 server-side-GAM approach (securepubads proxy, creative bundling) so reviewers can evaluate whether the Phase 1 architecture is shape-compatible with the eventual end state.

[aram356]

⛏ nitpick — Italics convention around the date.

Other specs in docs/superpowers/specs/ use a header like _Author · YYYY-MM-DD_ or omit the date entirely. Pick a convention so spec metadata is grep-able.