spec(tmp): IdentityMatch frequency-cap data flow + serve_window_sec#4070
Open
ohalushchak-exadel wants to merge 3 commits intomainfrom
Open
spec(tmp): IdentityMatch frequency-cap data flow + serve_window_sec#4070ohalushchak-exadel wants to merge 3 commits intomainfrom
ohalushchak-exadel wants to merge 3 commits intomainfrom
Conversation
Lands the IdentityMatch & frequency-capping architecture work from PR #3359 (bokelley/idmatch-design), but reframes the docs/trusted-match content around the data-flow boundary contract instead of prescribing internal implementation. Counting and policy live in the buyer's impression tracker, not in the IdentityMatch service. The IdentityMatch service maintains a narrow cap-state store keyed at (user_identity, seller_agent_url, package_id) with TTL expiration; the impression tracker writes a cap-fire entry on the impression that exhausts a cap; the IdentityMatch service checks presence at query time and excludes the package from eligible_package_ids. The reference cap-state store ships in adcp-go/targeting/fcap (Valkey 9 hashes with HSETEX). Wire spec changes (identity-match-response.json): - Adds serve_window_sec (1-300, default 60) - per-package single-shot fcap window. Replaces ttl_sec, which conflated router cache TTL with serve throttle and silently broke either when tuned. - Removes ttl_sec outright. TMP is pre-launch (experimental, pre-3.0.0 GA) and not subject to deprecation cycles. Doc updates: - docs/trusted-match/specification.mdx - adds serve_window_sec field, removes ttl_sec, adds normative conformance invariants for IdentityMatch eligibility (audience intersection; cap-state presence check; active state; audience freshness). - docs/trusted-match/identity-match-implementation.mdx (new) - frequency-cap data flow / boundary contract only. The protocol does not constrain how the impression tracker counts impressions, evaluates windows, or decides when a cap fires. - docs/trusted-match/buyer-guide.mdx - frequency-cap management section reflects the impression-tracker / IdentityMatch split. - docs/trusted-match/migration-from-axe.mdx - adds OpenRTB 2.6 User.eids[] cross-walk for buyers bridging from OpenRTB-shaped pipelines. - specs/identitymatch-fcap-architecture.md - design-history doc; earlier iterations (counter-based exposure tracking, log-based with impression_id dedup, fcap_keys label model) unwound as buyer-internal concerns the protocol shouldn't constrain. Co-Authored-By: Claude Opus 4.7 (1M context) <noreply@anthropic.com>
When fcap policies change (window length, max_count, activation, package reassignment), existing cap-state entries can become stale. The buyer's policy owner must re-evaluate every affected (user_identity, package) entry against the new policy and push delete-or-extend events to the cap-state store. - docs/trusted-match/identity-match-implementation.mdx — adds Policy updates and cap-state re-evaluation section with the two event shapes (delete / extend) and convergence requirement. - docs/trusted-match/buyer-guide.mdx — adds the re-evaluation requirement to the Frequency Cap Management section. - specs/identitymatch-fcap-architecture.md — adds decision #7 (policy updates trigger cap-state re-evaluation at the buyer); adds open question on an explicit delete primitive on the cap-state store. Co-Authored-By: Claude Opus 4.7 (1M context) <noreply@anthropic.com>
ohalushchak-exadel
force-pushed
the
ohalushchak-exadel/fcap-flow-docs
branch
from
9deca75 to
fee4ca0
Compare
BaiyuScope3
reviewed
May 5, 2026
BaiyuScope3
reviewed
May 5, 2026
BaiyuScope3
reviewed
May 5, 2026
- identity-match-response.json: remove `default: 60` from serve_window_sec. The field is in `required[]`, so a schema-level default never applies — it was misleading. Prose guidance in buyer-guide.mdx and specification.mdx still recommends 60 as the working default for senders. - migration-from-axe.mdx: RampID is person-based per IAB AdCOM v1.0 agent-type list, so both maintained and derived RampID map to atype 3. Adds a link to the IAB AdCOM spec for reference. Co-Authored-By: Claude Opus 4.7 (1M context) <noreply@anthropic.com>
BaiyuScope3
approved these changes
May 5, 2026
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
2 participants
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.
Summary
Lands the IdentityMatch & frequency-capping architecture work from #3359 (
bokelley/idmatch-design), but reframes thedocs/trusted-match/content around the data-flow boundary contract instead of prescribing internal implementation.The split:
(user_identity, seller_agent_url, package_id)with TTL expiration; at query time it checks presence and excludes capped packages fromeligible_package_ids.The reference cap-state store ships in
adcp-go/targeting/fcap(Valkey 9 hashes with HSETEX).Changes
Wire spec (
identity-match-response.json):serve_window_sec(1–300, default 60) — per-package single-shot fcap window.ttl_secoutright. TMP is pre-launch (experimental, pre-3.0.0 GA) and not subject to deprecation cycles.Docs:
docs/trusted-match/specification.mdx— addsserve_window_sec, removesttl_sec, adds normative conformance invariants (audience intersection; cap-state presence check; active state; audience freshness).docs/trusted-match/identity-match-implementation.mdx(new) — frequency-cap data flow / boundary contract only. Explicitly does not prescribe internal implementation.docs/trusted-match/buyer-guide.mdx— frequency-cap management section reflects the impression-tracker / IdentityMatch split.docs/trusted-match/migration-from-axe.mdx— adds OpenRTB 2.6User.eids[]cross-walk.specs/identitymatch-fcap-architecture.md— design-history doc; earlier iterations (counter-based exposure tracking, log-based withimpression_iddedup,fcap_keyslabel model) unwound as buyer-internal concerns.Test plan
serve_window_secschema validates (1–300, default 60, required).ttl_secno longer accepted inidentity-match-response.json./docs/trusted-match/identity-match-implementationreferences resolve.--empty(no protocol package version bump beyond what the schema change requires).🤖 Generated with Claude Code