feature(sdk) + docs(kb): curateAds — the D51 ad-dissemination helper (3.26.0) - #704
Open
jacoby149 wants to merge 1 commit into
Open
feature(sdk) + docs(kb): curateAds — the D51 ad-dissemination helper (3.26.0)#704jacoby149 wants to merge 1 commit into
jacoby149 wants to merge 1 commit into
Conversation
…(3.26.0) The per-creator choice of how their ads get mixed into a viewer's feed is a shared, deterministic SDK helper, not SQL. sdk/src/curate.ts exports curateAds(creatorAds, setting, state) → the ordered active subset to show, with four modes: round_robin (rotate past lastShown), pinned (the creator's pick), frequency_capped (drop ads shown cap× this session), and greedy (order by performance). Filters on body.status (showable unless paused). Canonical doc_id ordering makes the output independent of input order (pinned by a determinism test). The v0 greedy gap (operator-surfaced): greedy weights by offer performance, but the v0 ad object carries no stats (D55). So with no performance supplied, greedy degrades to round_robin (equal exposure — no ad starved) and becomes true greedy the instant the v4 metrics layer feeds performance in. KB ads.md Dissemination section updated (signature + the degradation note). 110 SDK tests green (22 new), typecheck + build clean.
This file contains hidden or bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
Sign up for free
to join this conversation on GitHub.
Already have an account?
Sign in to comment
1 participant
Add this suggestion to a batch that can be applied as a single commit.This suggestion is invalid because no changes were made to the code.Suggestions cannot be applied while the pull request is closed.Suggestions cannot be applied while viewing a subset of changes.Only one suggestion per line can be applied in a batch.Add this suggestion to a batch that can be applied as a single commit.Applying suggestions on deleted lines is not supported.You must change the existing code in this line in order to create a valid suggestion.Outdated suggestions cannot be applied.This suggestion has been applied or marked resolved.Suggestions cannot be applied from pending reviews.Suggestions cannot be applied on multi-line comments.Suggestions cannot be applied while the pull request is queued to merge.Suggestion cannot be applied right now. Please check back later.
What
The ads lane's second foundation: the
curateAdsD51 helper — the per-creator choice of how their ads get mixed into a viewer's feed, as a shared, deterministic SDK helper (not SQL).The stateful algorithms (round-robin needs "which ad showed last," greedy needs performance numbers) don't belong in a query, and being pure + shared means every app curates a given creator's ads identically from the same inputs.
The helper
The caller takes the first entry for a single post (the composer's "Rotate my ads") or the whole list for a curated-subset surface. Four modes:
round_robinlastShownDocId, wrap-aroundpinnedfrequency_cappedcap× this sessiongreedyFilters on
body.status(an ad is showable unlesspaused— status defaults toactive). The active set is canonically ordered bydoc_idfirst, so the output is independent of the order the ads arrive in (pinned by a determinism test).The v0
greedygap (operator-surfaced)greedyweights by offer performance, but the v0 ad object carries nostats(D55 — a counter is a write on a read path; impression/revenue verification is the v4 layer). So with noperformancesupplied,greedydegrades toround_robin(equal exposure — no ad starved) and becomes true greedy the instant the v4 metrics layer feeds per-ad scores intostate.performance. The other three modes need no metrics at all.This is documented in the KB (
ads.mdDissemination section) so it's not a silent lie.Notes
sdk/src/curate.ts(+curate.test.ts), exported fromindex.ts;dist/rebuilt.KB:
knowledge/knowledge-base/web10-v3/social/ads.md(Dissemination) +ads-catalog.md.