refactor(cf): per-tab state isolation with structural cross-tab filtering (#132)

Decompose CloudflareStateTracker (618 lines) into SessionSolverState
(shared Maps/Sets) + TabSolverState (per-tab scalar fields) + TabRuntime
(per-tab container). Replace the manual 3-step cross-tab OOPIF filter
chain with TabDetector service where filtering is baked in — impossible
to bypass.

Key changes:
- Extract startActivityLoop, takePendingRechallengeCount, bindPendingOOPIF helpers
- Split DetectorR into BaseDetectorR (no tab services) and full DetectorR
- Move deriveSolveAttribution/deriveFailLabel to cf-summary.ts
- Add TabSolverContext, TabDetector, SessionSolverContext services
- Per-tab services provided via Effect.provideService per detection fiber

Author: DivMode

src/session/cf/cf-services.ts

@@ -121,3 +121,61 @@ export const OOPIFChecker = ServiceMap.Service<{
 // ═══════════════════════════════════════════════════════════════════════
 
 export const SolverConfig = ServiceMap.Service<Required<CloudflareConfig>>('SolverConfig');
+
+// ═══════════════════════════════════════════════════════════════════════
+// SessionSolverContext — session-level shared state (provided once)
+//
+// Exposes the session-level Maps/Sets that detectors need for cross-tab
+// guards, OOPIF ownership tracking, and compound label accumulation.
+// ═══════════════════════════════════════════════════════════════════════
+
+export const SessionSolverContext = ServiceMap.Service<{
+  readonly iframeToPage: ReadonlyMap<TargetId, TargetId>;
+  readonly solvedCFTargetIds: ReadonlySet<string>;
+  readonly solvedPages: ReadonlySet<TargetId>;
+  readonly knownPages: ReadonlyMap<TargetId, CdpSessionId>;
+  readonly config: Required<CloudflareConfig>;
+  readonly destroyed: boolean;
+  readonly registerPage: (targetId: TargetId, cdpSessionId: CdpSessionId) => void;
+  readonly addSolvedCFTarget: (oopifId: string, pageTargetId: TargetId) => Effect.Effect<void>;
+  readonly addSolvedCFTargetSync: (oopifId: string, pageTargetId: TargetId) => void;
+  readonly pushPhase: (targetId: TargetId, type: string, label: string) => void;
+  readonly buildCompoundLabel: (targetId: TargetId) => string;
+}>('SessionSolverContext');
+
+// ═══════════════════════════════════════════════════════════════════════
+// TabSolverContext — per-tab isolated state (provided per tab runtime)
+//
+// Scalar fields, NOT Maps. Cross-tab contamination is structurally
+// impossible because there are no targetId keys to mix up.
+// ═══════════════════════════════════════════════════════════════════════
+
+import type { TabSolverState } from './cf-tab-state.js';
+
+export const TabSolverContext = ServiceMap.Service<{
+  readonly targetId: TargetId;
+  readonly cdpSessionId: CdpSessionId;
+  readonly state: TabSolverState;
+  /** Set the resolved pageFrameId — called once at detection start. */
+  readonly setPageFrameId: (id: string | null) => void;
+}>('TabSolverContext');
+
+// ═══════════════════════════════════════════════════════════════════════
+// TabDetector — per-tab filtered detection (structural cross-tab guard)
+//
+// The filtering is baked into the service implementation — impossible to
+// bypass. Replaces the 3-step manual filter chain:
+//   1. detectTurnstileViaCDP(cdpSessionId, solvedCFTargetIds)
+//   2. filterOwnedTargets(detection.targets, targetId, iframeToPage)
+//   3. pageFrameId ? filter by parentFrameId : keep all
+// with a single yield* call.
+// ═══════════════════════════════════════════════════════════════════════
+
+import type { CFDetected } from './cloudflare-solve-strategies.js';
+
+export const TabDetector = ServiceMap.Service<{
+  /** Returns ONLY OOPIFs belonging to this tab. Cross-tab OOPIFs are filtered by construction. */
+  readonly detect: (excludeTargetIds?: ReadonlySet<string>) => Effect.Effect<
+    CFDetected | { _tag: 'not_detected' }
+  >;
+}>('TabDetector');

src/session/cf/cf-session-state.ts

@@ -0,0 +1,173 @@
+/**
+ * Session-level shared state — extracted from CloudflareStateTracker.
+ *
+ * Contains Maps and Sets that are shared across all tabs in a session.
+ * Individual tabs reference this state through their tab runtimes.
+ * The session-level state outlives any individual tab.
+ */
+import { Effect, Exit, Scope } from 'effect';
+
+import { runForkInServer } from '../../otel-runtime.js';
+import type { CdpSessionId, TargetId, CloudflareConfig, CloudflareType } from '../../shared/cloudflare-detection.js';
+import { isInterstitialType } from '../../shared/cloudflare-detection.js';
+import type { CFEvents } from './cloudflare-event-emitter.js';
+import { DetectionRegistry } from './cf-detection-registry.js';
+
+export class SessionSolverState {
+  readonly registry: DetectionRegistry;
+  readonly iframeToPage = new Map<TargetId, TargetId>();
+  readonly knownPages = new Map<TargetId, CdpSessionId>();
+  readonly bindingSolvedTargets = new Set<TargetId>();
+  /** CF OOPIF targetIds from completed solves — filtered out of future detection polls. */
+  readonly solvedCFTargetIds = new Set<string>();
+  /**
+   * Page targetIds that have successfully solved an EMBEDDED TURNSTILE.
+   * See CloudflareStateTracker.solvedPages JSDoc for full rationale.
+   * DO NOT ADD INTERSTITIAL SOLVES — multi-phase (Int→Emb) flows will break.
+   */
+  readonly solvedPages = new Set<TargetId>();
+  readonly pendingIframes = new Map<TargetId, { iframeCdpSessionId: CdpSessionId; iframeTargetId: TargetId }>();
+  readonly pendingRechallengeCount = new Map<TargetId, number>();
+  /** Per-page reload count for widget-not-rendered recovery. Reset on solve. */
+  readonly widgetReloadCount = new Map<TargetId, number>();
+  /** Per-page cleanup scopes — finalizers remove solvedCFTargetIds entries when page is destroyed. */
+  private readonly pageCleanupScopes = new Map<TargetId, Scope.Closeable>();
+  config: Required<CloudflareConfig> = { maxAttempts: 3, attemptTimeout: 30000, recordingMarkers: true };
+  destroyed = false;
+  /** Per-page accumulator of solved/failed phases for compound summary labels. */
+  private readonly summaryPhases = new Map<TargetId, { type: string; label: string }[]>();
+
+  constructor(protected events: CFEvents) {
+    this.registry = new DetectionRegistry((active, signal) => {
+      const duration = Date.now() - active.startTime;
+
+      if (signal === 'verified_session_close') {
+        const phaseLabel = '⊘';
+        runForkInServer(Effect.logInfo(`Scope finalizer fallback: verified_session_close for ${active.pageTargetId}`));
+        this.pushPhase(active.pageTargetId, active.info.type, phaseLabel);
+        const compoundLabel = this.buildCompoundLabel(active.pageTargetId);
+        this.events.emitFailed(active, 'verified_session_close', duration, phaseLabel, compoundLabel,
+          { cf_verified: true });
+        return;
+      }
+
+      const failLabel = `✗ ${signal}`;
+      runForkInServer(Effect.logInfo(`Scope finalizer fallback: emitting failed for orphaned detection on ${active.pageTargetId}`));
+      this.pushPhase(active.pageTargetId, active.info.type, failLabel);
+      const compoundLabel = this.buildCompoundLabel(active.pageTargetId);
+      this.events.emitFailed(active, signal, duration, failLabel, compoundLabel);
+    });
+  }
+
+  /** Register a page target → CDP session mapping. Creates cleanup scope. */
+  registerPage(targetId: TargetId, cdpSessionId: CdpSessionId): void {
+    this.knownPages.set(targetId, cdpSessionId);
+    if (!this.pageCleanupScopes.has(targetId)) {
+      this.pageCleanupScopes.set(targetId, Scope.makeUnsafe());
+    }
+  }
+
+  /** Add OOPIF target ID to solvedCFTargetIds with scope-bound cleanup. */
+  addSolvedCFTarget(oopifId: string, pageTargetId: TargetId): Effect.Effect<void> {
+    return Effect.suspend(() => {
+      const scope = this.pageCleanupScopes.get(pageTargetId);
+      if (!scope) return Effect.void;
+      this.solvedCFTargetIds.add(oopifId);
+      return Scope.addFinalizer(scope, Effect.sync(() => {
+        this.solvedCFTargetIds.delete(oopifId);
+      }));
+    });
+  }
+
+  /** Synchronous variant — used where we're outside an Effect generator. */
+  addSolvedCFTargetSync(oopifId: string, pageTargetId: TargetId): void {
+    const scope = this.pageCleanupScopes.get(pageTargetId);
+    if (!scope) return;
+    this.solvedCFTargetIds.add(oopifId);
+    Effect.runSync(Scope.addFinalizer(scope, Effect.sync(() => {
+      this.solvedCFTargetIds.delete(oopifId);
+    })));
+  }
+
+  /** Look up page target by iframe CDP session. */
+  findPageByIframeSession(iframeCdpSessionId: CdpSessionId): TargetId | undefined {
+    return this.registry.findByIframeSession(iframeCdpSessionId);
+  }
+
+  pushPhase(targetId: TargetId, type: string, label: string): void {
+    if (!this.summaryPhases.has(targetId)) this.summaryPhases.set(targetId, []);
+    this.summaryPhases.get(targetId)!.push({ type, label });
+  }
+
+  /**
+   * Build compound summary label from accumulated phases.
+   * Interstitial phases: Int✓Int→ (no space). Embedded: Emb→.
+   * Space between groups: Int✓Int→ Emb→
+   */
+  buildCompoundLabel(targetId: TargetId): string {
+    const phases = this.summaryPhases.get(targetId) || [];
+    const intParts = phases
+      .filter(p => isInterstitialType(p.type as CloudflareType))
+      .map(p => `Int${p.label}`);
+    const embParts = phases
+      .filter(p => !isInterstitialType(p.type as CloudflareType))
+      .map(p => `Emb${p.label}`);
+    const parts: string[] = [];
+    if (intParts.length) parts.push(intParts.join(''));
+    if (embParts.length) parts.push(embParts.join(''));
+    return parts.join(' ');
+  }
+
+  /**
+   * Clean up all state for a destroyed page target.
+   * Registry.unregister() closes the detection's scope, whose finalizer
+   * emits session_close fallback if unresolved.
+   */
+  unregisterPage(targetId: TargetId): Effect.Effect<void> {
+    const self = this;
+    return Effect.fn('cf.state.unregisterPage')(function*() {
+      yield* Effect.annotateCurrentSpan({ 'cf.target_id': targetId });
+      yield* self.registry.unregister(targetId);
+
+      self.knownPages.delete(targetId);
+      self.iframeToPage.delete(targetId);
+      for (const [iframeId, pageId] of self.iframeToPage) {
+        if (pageId === targetId) self.iframeToPage.delete(iframeId);
+      }
+      self.bindingSolvedTargets.delete(targetId);
+      self.solvedPages.delete(targetId);
+      self.pendingIframes.delete(targetId);
+      self.pendingRechallengeCount.delete(targetId);
+      self.widgetReloadCount.delete(targetId);
+      self.summaryPhases.delete(targetId);
+
+      const cleanupScope = self.pageCleanupScopes.get(targetId);
+      if (cleanupScope) {
+        yield* Scope.close(cleanupScope, Exit.void);
+        self.pageCleanupScopes.delete(targetId);
+      }
+    })();
+  }
+
+  /** Emit cf.failed for orphaned detections and clean up all state. */
+  destroy(): Effect.Effect<void> {
+    this.destroyed = true;
+    return Effect.gen((function*(this: SessionSolverState) {
+      yield* this.registry.destroyAll();
+      this.iframeToPage.clear();
+      this.knownPages.clear();
+      this.bindingSolvedTargets.clear();
+
+      for (const scope of this.pageCleanupScopes.values()) {
+        yield* Scope.close(scope, Exit.void);
+      }
+      this.pageCleanupScopes.clear();
+
+      this.solvedCFTargetIds.clear();
+      this.solvedPages.clear();
+      this.pendingIframes.clear();
+      this.widgetReloadCount.clear();
+      this.summaryPhases.clear();
+    }).bind(this));
+  }
+}

src/session/cf/cf-summary.ts

@@ -1,13 +1,44 @@
 /**
- * Pure summary functions for CF replay markers.
+ * Pure summary functions for CF replay markers and solve attribution.
  *
- * Extracted from integration-helpers.ts so unit tests can import
- * without triggering env var validation (REPLAY_INGEST_URL, etc.).
+ * Extracted from integration-helpers.ts and cloudflare-state-tracker.ts
+ * so unit tests can import without triggering env var validation.
  */
 
 import { isInterstitialType } from '../../shared/cloudflare-detection.js';
 import type { CloudflareType } from '../../shared/cloudflare-detection.js';
 
+// ── Solve Attribution (moved from cloudflare-state-tracker.ts) ─────
+
+export type SolveSignal = 'page_navigated' | 'beacon_push' | 'token_poll' | 'activity_poll'
+  | 'bridge_solved' | 'state_change' | 'callback_binding' | 'session_close' | 'cdp_dom_walk'
+  | 'verified_session_close';
+
+// ┌──────────────┬──────────────────┬──────────────┬───────┐
+// │ Signal       │ clickDelivered?  │ Method       │ Label │
+// ├──────────────┼──────────────────┼──────────────┼───────┤
+// │ page_nav     │ true             │ click_nav    │  ✓    │
+// │ page_nav     │ false            │ auto_nav     │  →    │
+// │ any other    │ true             │ click_solve  │  ✓    │
+// │ any other    │ false            │ auto_solve   │  →    │
+// └──────────────┴──────────────────┴──────────────┴───────┘
+
+export function deriveSolveAttribution(signal: SolveSignal, clickDelivered: boolean) {
+  if (signal === 'page_navigated') {
+    return clickDelivered
+      ? { method: 'click_navigation' as const, autoResolved: false, label: '✓' }
+      : { method: 'auto_navigation' as const, autoResolved: true, label: '→' };
+  }
+  return clickDelivered
+    ? { method: 'click_solve' as const, autoResolved: false, label: '✓' }
+    : { method: 'auto_solve' as const, autoResolved: true, label: '→' };
+}
+
+export function deriveFailLabel(reason: string) {
+  if (reason === 'verified_session_close') return { label: '⊘' };
+  return { label: `✗ ${reason}` };
+}
+
 // ── CF Markers Reference ─────────────────────────────────────────────
 
 export interface ReplayMarker {

src/session/cf/cf-tab-runtime.ts

@@ -0,0 +1,35 @@
+/**
+ * Per-tab runtime state container.
+ *
+ * Each tab gets its own TabRuntime containing TabSolverState with scalar
+ * fields (not Maps). Cross-tab contamination is structurally impossible
+ * because there are no targetId keys to mix up.
+ *
+ * State is GC'd when the TabRuntime entry is deleted from the map —
+ * no manual per-field cleanup needed.
+ */
+import type { CdpSessionId, TargetId } from '../../shared/cloudflare-detection.js';
+import { TabSolverState } from './cf-tab-state.js';
+
+/** Per-tab state container. */
+export interface TabRuntime {
+  readonly state: TabSolverState;
+  readonly targetId: TargetId;
+  readonly cdpSessionId: CdpSessionId;
+  /** Resolved by detectTurnstileWidgetEffect at detection start. */
+  pageFrameId: string | null;
+}
+
+/** Create a per-tab state container. */
+export function makeTabRuntime(opts: {
+  targetId: TargetId;
+  cdpSessionId: CdpSessionId;
+  pageFrameId: string | null;
+}): TabRuntime {
+  return {
+    state: new TabSolverState(),
+    targetId: opts.targetId,
+    cdpSessionId: opts.cdpSessionId,
+    pageFrameId: opts.pageFrameId,
+  };
+}

src/session/cf/cf-tab-state.ts

@@ -0,0 +1,22 @@
+/**
+ * Per-tab mutable state. Scalar fields, NOT Maps.
+ * Created per tab, GC'd with tab runtime disposal.
+ *
+ * By using scalar fields instead of Map<TargetId, X> entries,
+ * cross-tab contamination is structurally impossible — there's no
+ * targetId key to mix up.
+ */
+import type { CdpSessionId, TargetId } from '../../shared/cloudflare-detection.js';
+
+export class TabSolverState {
+  /** Whether the CF bridge push has already fired a solved event for this tab. */
+  bindingSolved = false;
+  /** Pending OOPIF that arrived before detection registered (race condition). */
+  pendingIframe: { iframeCdpSessionId: CdpSessionId; iframeTargetId: TargetId } | null = null;
+  /** Number of CF rechallenges on this tab so far. */
+  rechallengeCount = 0;
+  /** Per-tab reload count for widget-not-rendered recovery. Reset on solve. */
+  widgetReloadCount = 0;
+  /** Per-tab accumulator of solved/failed phases for compound summary labels. */
+  summaryPhases: { type: string; label: string }[] = [];
+}