Content controller hardening: dispose guard, concurrent-evaluate store race, session-exemption TTL/scoping

[i8ramin]

Umbrella for content-controller robustness gaps surfaced while dogfooding the Dupe extension migration onto standdown and by a high-effort review of the SPA re-evaluation example (#51). Grouping them so the tradeoffs are considered together.

1. Public evaluate() ignored the disposed flag — being fixed in #51

The internal scheduleEvaluation guards on disposed (src/content.ts), but the public evaluate() (src/content.ts:118) did not. Once we recommend adopters drive evaluate() from their own navigation signal (a timer or router hook), a caller that forgets to tear that signal down keeps re-running a disposed controller and re-firing onDecision after dispose().

Fix (in #51): evaluate() now returns a fail-closed controller-disposed decision and does not fire onDecision once disposed. Small guard + test. This is the sharpest edge and is handled.

2. Concurrent evaluate() calls can lose-update the session store

session.ingest -> #withState does an unlocked async load -> modify -> save (src/session.ts:221-268). Through the adapter's own hooks this never overlaps, because scheduleEvaluation coalesces via a pending flag. But external evaluate() callers are not coalesced, so two overlapping evaluations (e.g. an adopter's nav hook firing while a popstate evaluation is mid-flight) can interleave: the second load reads pre-write state and its save drops the first evaluation's record. Worst case a stand-down record is lost and the extension activates on an already-attributed page.

Options:

• Serialize #withState with a small promise-chain / mutex so writes never interleave (fixes it for all callers, including future adapters).
• Or route public evaluate() through the same pending-style coalescing the internal path uses.

Serializing #withState is the more general fix and keeps the public API a plain evaluate().

3. Session self-exemptions have no TTL and no value/click-id scoping

(From the extension review, Rusty's comment on selfExemptionScope: 'session'.) Session exemptions are keyed by host + policyId/networkId with a grantedAt but no expiry (recordSessionExemptions/applySessionExemptions, src/session.ts:402-476). So after landing via our own CJ link, a later click on a competitor's CJ link back to the same host in the same tab (same cj policyId) gets its match stripped and we skip standing down.

This is intentional ignore_param-parity behavior today (documented at src/types.ts:214-217), and ADOPTING.md already warns to use 'session' scope only when the homegrown code actually persisted the exemption. So this is a design question, not a bug:

• Do we want an optional TTL on session exemptions?
• Or per-value / per-click-id scoping so an exemption only clears the same attribution it was granted for, not any later same-network click?

Lower priority than 1 and 2, and would change documented behavior, so wants a deliberate decision.

Suggested sequencing

1 lands in #51. 2 is a self-contained follow-up (serialize #withState + a concurrency test). 3 is a design discussion to schedule separately.

[i8ramin]

Item 3: session-exemption TTL / value-scoping — options

Writing up the design space so we can make a call. This one changes documented ignore_param-parity behavior, so it wants a deliberate decision rather than a quiet patch.

Current behavior (for reference)

With selfExemptionScope: 'session', an ExemptionRecord is stored per advertiser host:

{ advertiserHost, policyIds[], networkIds[], grantedAt }

• recordSessionExemptions (src/session.ts:429) adds the matched self-pattern's policyId/networkId to the host's record. It is monotone (never grants while a stand-down is already active) and grantedAt is set once and never refreshed.
• applySessionExemptions (src/session.ts:475) drops any later matched rule whose policyId/networkId is in the host's record (except disabled-host), then recomputes the strongest match.
• There is no expiry: pruneExpiredSessions (src/session.ts:618) prunes state.sessions only, never state.exemptions. The record lives for the lifetime of the session state (or the local-ttl envelope).

The record is scoped to (host, policyId/networkId) but not to the specific attribution value that earned it.

The edge case

Land on merchant.com via our CJ link, then in the same session click a competitor's CJ link back to merchant.com. The competitor's CJ match is the same policyId: 'cj', so applySessionExemptions drops it and we do not stand down. We keep a sale we should have ceded.

The core tension

The entire thing 'session' scope adds over the default 'policy' scope is suppressing later same-network attribution on a host. A param-less later navigation has no match to drop anyway, so session scope only changes an outcome when a later nav carries same-network attribution. That is exactly the hijack surface. So the honest framing is: 'session' scope is inherently more permissive, and Rusty's edge case is the visible tip of that, not a separable bug.

Options

Option A — value / click-id scoping (most precise)
Record the self-param value that earned the exemption, and only suppress a later match whose attribution value equals it. A competitor's CJ click carries a different value, so it stands down; our own value (or a param-less nav) still gets exempted.

• Fixes the edge case exactly.
• Cost: thread the matched attribution value through Detection/MatchedRule into the exemption compare, and store value(s) per scope. Moderate.
• Note: in the classic ignore_param case where a merchant re-decorates with a real CJ param that isn't ours, Option A would stand down. That is arguably the correct, honest outcome, but it is a behavior change from today.

Option B — TTL / expiry on exemptions (bounds, does not eliminate)
Give ExemptionRecord an expiresAt and prune it alongside sessions.

• Cheap and low-risk: mirrors the existing SessionRecord.expiresAt + pruneExpiredSessions machinery.
• Bounds the hijack window instead of closing it: within the TTL a competitor's same-network click on the same host is still suppressed.
• Open sub-decisions: fixed-from-grant (safer, bounds total window) vs sliding (resets on each self-touch); default TTL and whether it is configurable (sessionExemptionTtlMs).

Option C — only re-apply to non-competing navigations (fix via the existing self-match signal)
Tighten applySessionExemptions so it does not drop a match that represents fresh, non-self attribution this navigation. We already compute selfExemptScopes per nav (src/types.ts:161) from value-specific selfPatterns, so a competitor's CJ param is present in matched but absent from selfExemptScopes. Suppress only when the scope is not currently carrying a non-self match.

• Same outcome as Option A for the competitor case, with no new stored state (uses the value-specific self-match we already have).
• Keeps the legit param-less re-application, which is the real point of session scope.
• Also a behavior change in the merchant-re-decorates case, same as A.

Option D — keep behavior, strengthen the guardrail
Leave the semantics, make ADOPTING.md and the selfExemptionScope doc even blunter about the tradeoff, and lean on 'policy' being the safe default.

• Zero code risk. Rusty flagged this as niche and non-blocking.
• Does nothing for adopters who legitimately need 'session' (our own extension migration uses it), so the sharp edge stays.

Recommendation

Two things, sequenced:

1. Ship Option B (TTL) now as a cheap, general safety bound. "Exemptions never expire" is worth fixing on its own, independent of the competitor case, and it reuses machinery we already have. I would default to fixed-from-grant with a configurable sessionExemptionTtlMs.
2. Do Option C as the real fix (precise, no new state, reuses the self-match signal), gated on your call, since it changes the documented ignore_param-parity behavior in the merchant-re-decorate case. I lean toward C over A because it needs no schema change and leans on the value-specific self-match we already trust.

Option D alone feels too weak given our own adopter is on 'session'.

If you agree with B + C, I will split them into two PRs (B first, since it is low-risk and independent) and keep each behind a test that pins the competitor-click case. What is your call on: (a) B's default TTL and configurability, and (b) whether C's behavior change in the merchant-re-decorate case is acceptable?

[i8ramin]

All three items resolved and shipped in v0.3.3 (and earlier).

• Item 1 — public evaluate() now fails closed after dispose() (fix(content): evaluate() safe after dispose + document isolated-world SPA nav limitation #51).
• Item 2 — session state read-modify-write is serialized against lost updates (fix(session): serialize state read-modify-write to prevent lost updates #55).
• Item 3 — session self-exemptions now have a TTL (default 30m, feat(session): TTL for session self-exemptions (default 30m) #56) and no longer swallow a competing attribution param (fix(session): session exemption must not swallow a competing attribution param #57).

Closing. Thanks to the extension-migration review for surfacing all of these.