Click context: ctx_token issuance, carriage, discovery and resolution

[jalexspringer]

The single click-context change dispositioned in #23, #28 and #30, replacing the v0.1 click manifest with the click context (new §7.4).

Token and binding (#28). ctx_token gains the value pattern ^ct_[A-Za-z0-9_-]{8,240}$ and MUST bind to exactly one presentation at mint time — the same URL presented twice gets two tokens. Surfaces that route outbound navigation mint per click. The token→presentation binding is issuer state: destinations no longer receive presentation_id, and the consumer restores the binding at resolution. presentation_id is now conditional — required on agent-reported engagements, not on envelopes carrying ctx_token.

Carriage (#23). Reserved query parameters ctx_token and ctx_iss; SHOULD-level redirect-chain propagation mirroring §7.2.

Discovery (#30). ctx_iss is an issuer manifest locator resolving through §8.1 well-known discovery to the new telemetry.ctx_resolution endpoint. Token stays opaque; no central registry.

Resolution (#28, amended in review). The response is the engagement, the clicked content's lineage selected by content identity across all turns (not a turn or timestamp cut), a contributing-source set gated per contributing owner's recorded opt-in and scoped to the engaged presentation's turn (restoring the v0.1 click manifest's consent-gated role — review follow-up, 50cf32a), and an optional count-based session summary. Never the raw session_id; never events for owners without a recorded opt-in. Migration note covers the rescoping from the v0.1 click manifest.

Owner-scoped engagement delivery (#28, added in review). New §7.4.5: the agent-authored click content_engaged MUST appear in the engaged content owner's §7.3 filtered view on the same terms as grounding and citation events, session_id included — the §7.4.4 prohibition binds token resolution, not owner-scoped reporting. Recorded limit renumbered to §7.4.6.

Recorded limit (#29). §7.4.5 documents the consumer-custody dependency and the profile route for decentralised settlement.

Fixtures: repeated-link engagement, earlier-turn click, redirect destination report, agent manifest with ctx_resolution, bad-pattern token, and agent-reported engagement missing both presentation_id and token. Conformance suite 74/74, worked examples 9/9.

Design note: settled per the dispositions posted 12 August on #23/#28/#30.

🤖 Generated with Claude Code

[pedroamaralsantos]

This new section §7.4.4 isn't compatible with attribution.

The previous click manifest returned (consent-gated) content_grounded / content_cited / content_presented for the session — the sources that informed the response that produced the click. That is what let a destination or network credit publishers, not only the clicked URL.

This PR replaces that with lineage selected by content identity of the clicked reference. That works when the user clicks the publisher’s own article. It fails the common commerce case:

• User reads publishera.com (grounded / cited / presented)
• User clicks through to advertiser.com
• content_engaged.content_url is the advertiser

Resolve then returns only events whose content_url / content_id match advertiser.com. Publisher A’s events are excluded because they are a different content identity.

For an affiliate network (or any party holding the ctx_token on the advertiser hop), that is the join we need: this click on advertiser.com was contributed by publishera.com. Without it, resolve can corroborate the destination click but cannot support multi-citation attribution.

We understand the privacy goal — a token must not dump other owners’ events indiscriminately, and we are not asking to return the whole session. We are asking that resolve still expose the consent-gated contributing sources for this click, not only the clicked content’s own lineage. Could v1 keep a gated contributing-source set on the click context (closer to the old manifest role), alongside engagement + lineage of the clicked content? This is very important for attribution.

Thank you

[jalexspringer]

Accepted — you are right, and the fix is in 50cf32a. Lineage by content identity alone cannot support the case you describe: the click on advertiser.com resolves nothing about publishera.com, which is precisely the join an affiliate network needs.

The distinction I want to hold is not events-versus-counts, it is gated-versus-indiscriminate. The objection to a timestamp cut was that any token holder could stream other owners' activity without those owners' say. The v0.1 click manifest never actually had that problem — it was gated by per-owner opt-in, and the v1 narrowing dropped the component instead of keeping the gate. That was the wrong cut.

§7.4.4 now defines the click context as four components: the engagement, the clicked content's lineage by identity, the contributing sources — grounded events in scope for the engaged presentation's turn plus that turn's citation and presentation events, for content other than the clicked content, each owner's events included only under that owner's recorded contributing-source opt-in with the resolving consumer — and the count-based summary. Owners without an opt-in stay counts-only. Since a contributing publisher's interest is to be credited, the opt-in aligns with the incentive; the gate is what keeps an owner's activity from being disclosed against its will. §12.1 now reads as a scoping (whole session → the click's turn) with the same gate, rather than a removal.

Scope is the click's turn, not turns 1..M at click timestamp — the earlier-turns concern from the issue thread is largely covered by session-scoped groundings remaining in scope for the turn, and anything beyond that is session reporting under §7.3, where your second comment now does the heavy lifting (see below).

[pedroamaralsantos]

Thanks for preparing the PR. We wanted to come back to one point from #28 that was never answered in the issue discussion and is not addressed in this PR. It remains very important to us for v1.

Our proposal is that the agent-authored click content_engaged event MUST be delivered to the destination content owner when they are participating in telemetry (§7.3 owner-scoped routing), with the session_id included in the server-side delivery — just like grounding/citation events today.

This is essential for the following reasons:

• Even when the ctx_token is lost in the redirect chain, the destination owner is still notified of the click via the server-side event.
• It reduces the dependency on the telemetry consumer to resolve the token.
• Affiliate networks can process the owner-scoped streams of their clients (publishers and advertisers) and match events on session_id for attribution.
• Even aside from attribution, an advertiser can group their own grounded/cited events with the click content_engaged without having to query a resolver.

This is not the same as distributing the click token to every content owner (the privacy concern recorded in §7.4.5). It is the same isolation as today: only the owner of the clicked content_url receives their agent-authored content_engaged, with session_id, under §7.3 — the same pattern as content_grounded and content_cited.

(I will be on vacation until August 24, starting today)
Thank you

[jalexspringer]

Replying to the owner-delivery point — this should have been answered in the #28 disposition, apologies for the gap. Accepted for v1, in 50cf32a.

New §7.4.5 (the recorded limit moves to §7.4.6): the agent-authored click content_engaged is a session event like any other, and a consumer providing owner-filtered views MUST include it in the engaged content owner's view on the same terms as content_grounded and content_cited — session identifier included. The §7.4.4 session_id prohibition binds token resolution, where the requester is authenticated by nothing more than possession of a URL-carried value; it does not bind §7.3 delivery to an owner whose domain registration the consumer has verified. You had this exactly right: it is the same isolation as today, not token distribution — only the owner of the clicked content_url receives the event, and contributing owners still receive no token.

That covers all four of your reasons: the destination is notified even when ctx_token dies in the redirect chain; the destination's own join needs no resolver; a network processing owner-scoped streams for both a publisher and an advertiser matches its clients' events on session_id; and an advertiser groups its own grounded/cited events with the click directly. The owner's filtered view SHOULD also carry the event-level ctx_token, so a destination that captured the query parameters at landing can tie the URL-channel observation to the server-side event without any lookup.

Together with the gated contributing-source component (thread above), the two paths compose: owner-scoped streams for parties with verified domain standing, gated resolution for parties that only hold the click chain.

This lands before the 21 August freeze; happy to revisit wording when you are back on the 24th. Enjoy the break.

[jalexspringer]

Merged into v1-draft ahead of the 21 August freeze, rebased onto the post-#10 head. Both review points are in as accepted: the consent-gated contributing-source set restored in §7.4.4 and owner-scoped delivery of the click content_engaged in §7.4.5, landed in 50cf32a (af939c9 after rebase). Conformance suite 80/80, worked examples 9/9, CI green on the merge. @pedroamaralsantos if anything in the landed text still falls short of the affiliate case, please open an issue and we will treat it as a freeze-window fix.