feat(preview): experiment preview — debug_token + set_preview (qs-03)

[abbaseya]

Summary

Implements qs-03 Experiment Preview for the Convert Ruby SDK — an additive, SDK-only feature (no API endpoint, no OpenAPI, no backend, no bucketing-contract change). Two capabilities from the normative cross-SDK contract:

• (A) debug_token: config option — a QA config-transport option. When set, every config-fetch URL carries debug_token=<value> and _conv_low_cache=1 (forced regardless of cache_level); config caching is disabled (always live, no store read-fallback and no cache write, so a shared store is never poisoned with the status-widened debug config); the token is redacted like sdk_key_secret and never sent to the track endpoint.
• (B) Per-context preview input — context.set_preview(experience_id:, variation_id:) force-decides one variation with full bypass (audiences/segments/locations/environment/status/traffic/stored-decisions/bucketing-hash) and zero trace (no track requests, no visitor-state store writes, across the whole lifecycle including the at_exit flush). Canonical link param convert_preview={experienceId}.{variationId} parsed by the pure helper ConvertSdk.parse_preview_param.

Stacked PR — base is feat/ruby-sdk-cache-level (the open qs-02 PR #40), NOT master. This reuses the qs-02 _conv_low_cache append seam on that base. Merge qs-02 (#40) first.

Acceptance criteria (AC1–AC10) — all covered

AC	Coverage
AC1 debug_token transport	config_url forces _conv_low_cache=1 + appends debug_token=; composes with environment; refresh path inherits
AC2 always-live	no store read-fallback and no cache write under debug_token
AC3 token hygiene	redacted like sdk_key_secret; absent from to_internal (never tracked)
AC4 forced decision	set_preview resolves in-config or via ?exp= fetch; run_experience short-circuits the forced variation
AC5 full bypass	DataManager#get_preview_decision pure, bypasses every gate (draft/paused/mismatched-env/stopped/zero-traffic/stored-decision)
AC6 zero trace	no enqueue (suppressed at source → empty queue → at_exit/flush no-op) + no store write across run_experience(s)/run_feature(s)/track_conversion/segments
AC7 isolation	preview state per-context; concurrent non-preview context buckets/persists/tracks normally; shared config deep-frozen (no mutation leak)
AC8 memoization	process-wide 60s fork-safe memo keyed sdk_key:experience_id, one fetch per key/window, evicts expired entries on write
AC9 parse helper	parse_preview_param("123.456") → ["123","456"]; malformed → nil
AC10 regression lock	full existing suite green; RBS/steep updated for all new public API

Implementation tasks (beads epic ai-driven-product-dev-gc7u)

• RB-1 debug_token config option + config_url transport + always-live + hygiene
• RB-2 ConvertSdk.parse_preview_param pure helper
• RB-4 DataManager#get_preview_decision pure full-bypass
• RB-3 ApiManager#get_config_by_experience + process-wide 60s fork-safe memo
• RB-5 Context#set_preview + forced-decision path + isolation
• RB-6 zero-trace hardening (suppress all tracking + all store writes on a preview context)
• Review R1 fixes: memo eviction on write (parity + unbounded-growth guard); zero-trace test lock-in for plural/feature paths

Design note — deliberate Ruby/JS divergence (audited)

On a preview context, genuinely-decided OTHER experiences still fire the SystemEvents::BUCKETING lifecycle event (Ruby's Story 4.5 invariant: the lifecycle event is decisioning observability that fires even under consent denial; only the outbound enqueue is gated). JS wraps this in if (!this._preview). Zero-trace per the spec is defined over track requests + visitor-state persistence — not the in-process pub/sub event — so AC6 holds (0 POSTs, empty queue, 0 store writes). An independent decision-audit (analyst → auditor) verified this PASS.

Test plan

• Full suite green: 1318 examples, 0 failures (spec/unit spec/integration spec/cross_sdk spec/docs)
• steep check clean; rbs validate clean; rubocop lib/ clean
• Decision audit PASS (10 decisions, independent analyst + auditor)
• Code review clean after round 2

Human follow-up (separate repos — cannot edit here)

• ruby-sdk wiki Configuration.md option table: add a debug_token row + a "Preview / QA" section (the canonical option table the README defers to lives in the separate wiki repo).
• Shared "QA & Preview for Fullstack" guide + UI "Copy preview link" work are out of this repo's scope (recorded in the spec's rollout notes).

🤖 Generated with Claude Code

[gemini-code-assist]

Code Review

This pull request implements the experiment preview feature (qs-03), introducing a debug token configuration, experience-scoped config fetching with process-wide memoization, and a zero-trace preview context that suppresses tracking and persistence writes. The feedback highlights several critical robustness improvements: preventing invalid CDN requests in data-only mode when the SDK key is nil, avoiding a potential memory leak by referencing the class directly in a global ForkGuard callback, and defensively converting experience and variation IDs to strings to prevent TypeErrors during URL generation.

Important

The consumer version of Gemini Code Assist on GitHub is being sunset. Starting June 18, 2026, new organization installations will be blocked, and all code review activity will officially cease on July 17, 2026.
For more details on the timeline and next steps, please review the Help Documentation.

[JosephSamirL]

Review — experiment preview (qs-03): debug_token + set_preview

Verdict: Approve with minor changes. The implementation is correct, well-tested, and faithfully mirrors the JS oracle on every substantive contract. I found one comment that misrepresents the oracle (with a small, real behavioral divergence behind it), one undocumented divergence, and a stale PR description. Nothing blocks merge on correctness.

How this was verified (against the actual oracle, not the PR's paraphrase)

• Read the full +1983/−59 diff across all 26 files, with the branch checked out for surrounding context on every seam.
• Compared each Ruby behavior to the actual JS source at javascript-sdk@feat/experiment-preview (head 487f8f6) — context.ts, data-manager.ts, api-manager.ts, segments-manager.ts, parse-preview-param.ts — line by line.
• Traced the live Ruby seams: fire_bucketing/suppress_bucketing_enqueue?, get_preview_decision→retrieve_variation/build_bucketed_variation (confirmed pure + full-bypass), persist_bucketing's enable_storage gate, the feature_manager → get_bucketing → persist_bucketing chain, and to_internal (explicit allowlist — debug_token absent by construction).
• Ran it: full suite 1320 examples / 0 failures, rubocop lib/ clean, rbs validate clean, steep check clean, 97.9% line coverage.

---

🟡 F1 (Medium) — update_visitor_properties under preview diverges from JS, and its comment misstates the oracle

Ruby gates only the store write behind if @preview.nil?, then runs @attributes = @attributes.merge(normalised) unconditionally — so under preview the in-memory merge still happens (locked by context_preview_zero_trace_spec.rb:2466-2474).

The JS oracle does the opposite — context.ts:622-630:

updateVisitorProperties(visitorId, visitorProperties) {
  if (this._preview) return;                 // public method returns ENTIRELY
  this._dataManager.putData(visitorId, {segments: visitorProperties});
}

The Ruby comment claims "JS's public updateVisitorProperties has no preview guard of its own, but the PRIVATE helper it calls to persist DOES skip entirely under preview … leaving the in-memory side unaffected there too." That is wrong on three counts: the guard is in the public method (line 628, not a private helper); putData has no gate (the JS comment itself says so); and JS does no in-memory merge here — it returns first.

Impact: low but real. @attributes feeds decision_attributes → audience matching, so on a preview context update_visitor_properties changes how other experiences decide in Ruby but not JS. It's in-memory only, so zero-trace (track requests + store writes) is not violated — but it's an observable parity delta in a parity-defined feature, and the comment will mislead the next maintainer.

Fix: either (a) match JS — return self before the merge under preview (and update that one test), or (b) keep the Ruby behavior but rewrite the comment to state the truth and add it to the deliberate-divergence list. The mis-describing comment should go either way.

🟢 F2 (Low) — set_preview failure paths don't reset a prior preview; JS does

JS nulls _preview when the experience or variation can't be resolved (context.ts:172,182,195); Ruby's warn_preview_inert intentionally leaves @preview untouched. Only manifests on a re-preview (a 2nd set_preview after a good one) with bad input: JS drops preview mode, Ruby keeps the prior preview. Ruby's choice is arguably safer, but it's an undocumented divergence — match JS, or add a one-liner to the divergence list.

⚪ F3 (Housekeeping) — PR description is stale

The description still says "base is feat/ruby-sdk-cache-level (#40) … Merge qs-02 (#40) first." #40 has merged and this PR auto-retargeted to feat/fullstack-v12; the diff is now clean qs-03-only. Worth updating so reviewers aren't chasing a phantom stacked dependency.

---

✅ On the one deliberate divergence (BUCKETING event) — concur with the PASS

Under preview, other experiences still fire SystemEvents::BUCKETING in Ruby (only the enqueue is suppressed), whereas JS wraps every fire in if (!this._preview) (context.ts:260,320,391,412,472). Verified against both the oracle and Ruby's fire_bucketing (event always fires; enqueue gated by track:). The Story 4.5 rationale (BUCKETING is decisioning observability, orthogonal to the tracking switch) is sound and consistent with how Ruby already treats consent-denied tracking. Not a defect — noting only so the reviewer consciously accepts that a Ruby preview context emits BUCKETING events to subscribers where JS emits none.

Minor notes (not blockers)

• Memo concurrency: JS caches the in-flight Promise so concurrent same-key callers coalesce to one fetch; Ruby's synchronous read-miss → fetch → write isn't atomic, so N concurrent first-callers for the same (sdk_key, experience_id) could each fetch. Benign (correct data, last-write-wins) and preview is a low-concurrency QA path; AC8's "one fetch per key/window" holds for sequential lookups.
• run_experiences doesn't force the target's preview variation — but this is exact JS parity (JS runExperiences also decides the target naturally under preview; only runExperience short-circuits). Shared characteristic, not a Ruby bug.
• URL encoding: Ruby URL-encodes exp/environment/debug_token; JS interpolates raw. No practical difference for numeric ids / typical tokens; Ruby is marginally safer.

Strengths worth calling out

• parse_preview_param is an exact parity match including the subtle newline edge — Ruby correctly chose \A\d+\z (\z, not \Z) to match JS's non-multiline ^\d+$.
• Token hygiene is airtight: to_internal is an explicit allowlist (token absent by construction), secret-registration wired, URL-query stripping covers the logged-URL case — all tested.
• One clean seam (enable_storage: @preview.nil? through decision_attributes) covers experiences and features for persistence suppression — the feature chain plumbs it through intact.
• get_preview_decision is genuinely pure/full-bypass (verified internals, test-locked with store spies), and the config-cache-poisoning guard (config_cache_disabled) is a thoughtful Ruby-only hardening beyond parity.

---

Reviewed with Claude Code. Findings F1/F2 verified against javascript-sdk@feat/experiment-preview head 487f8f6; suite/rubocop/rbs/steep run locally on the PR head.