playwright-intelligence-engine 0.0.0-stage → 2.0.0

package/src/selector/selector-scorer.ts

@@ -0,0 +1,344 @@
+import { ResolvedElement } from '../trace/snapshot-resolver.js';
+
+export interface ScorerWeights {
+  wU: number; // Uniqueness
+  wI: number; // Identity Match
+  wM: number; // Semantic Match (Role/Label over raw CSS)
+  wA: number; // Actionability (visible/enabled)
+  wH: number; // Historical Execution Reliability
+  wD: number; // Volatile Implementation Dependence penalty
+}
+
+export interface ScoreBreakdown {
+  score: number;
+  transformedScore: number;
+  calibratedProbability: number; // Retained as alias for transformedScore
+  uniqueness: number;
+  matchCount: number;
+  identityMatch: number;
+  semanticMatch: number;
+  actionability: number;
+  historicalReliability: number;
+  historicalExecutionReliability: number;
+  volatilePenalty: number;
+  conventionAlignment?: number;
+  explanation: string[];
+}
+
+export interface SelectorProjectContext {
+  preferredLocator?: 'getByRole' | 'getByTestId' | 'getByLabel' | 'getByText' | 'locator' | 'unknown';
+  /** Observed locator counts from the repository profile. */
+  locatorUsage?: Partial<Record<'getByRole' | 'getByTestId' | 'getByLabel' | 'getByText' | 'locator', number>>;
+}
+
+const SEMANTIC_INTENT_GROUPS: string[][] = [
+  ['login', 'log in', 'signin', 'sign in', 'authenticate'],
+  ['logout', 'log out', 'signout', 'sign out'],
+  ['submit', 'save', 'confirm', 'send', 'apply'],
+  ['cancel', 'close', 'dismiss', 'abort'],
+  ['checkout', 'pay', 'payment', 'order'],
+];
+
+function semanticIntentGroup(value: string): string[] | undefined {
+  return SEMANTIC_INTENT_GROUPS.find((group) => group.some((term) => value.includes(term)));
+}
+
+export class SelectorScorer {
+  public static readonly DEFAULT_WEIGHTS: ScorerWeights = {
+    wU: 0.25,
+    wI: 0.25,
+    wM: 0.20,
+    wA: 0.15,
+    wH: 0.10,
+    wD: 0.20,
+  };
+
+  /**
+   * Scores a candidate element against the multi-factor formula:
+   * S(L) = w1*U + w2*I + w3*M + w4*A + w5*H - w6*D
+   *
+   * Uniqueness evaluates whether the proposed locator resolves to exactly one element.
+   * Identity requires affirmative token overlap and rejects contradictory semantics.
+   * Actionability verifies enabled state and non-hidden status.
+   * Produces a transformed score (sigmoid scaling), not an overclaimed empirical probability.
+   */
+  public static score(
+    candidate: ResolvedElement,
+    allCandidates: ResolvedElement[],
+    originalSelector?: string,
+    historicalScore?: number,
+    weights = SelectorScorer.DEFAULT_WEIGHTS,
+    projectContext?: SelectorProjectContext,
+  ): ScoreBreakdown {
+    const explanation: string[] = [];
+
+    // 1. Uniqueness U: Evaluated on actual candidate identifying attributes
+    const matchingCount = allCandidates.filter((c) => {
+      // If role + name exists, check match on role + name
+      if (candidate.role && candidate.accessibleName) {
+        return c.role === candidate.role && c.accessibleName === candidate.accessibleName;
+      }
+      // If testid exists, check match on testid
+      const candTestId = candidate.attributes?.['data-testid'] ?? candidate.attributes?.['data-test'];
+      if (candTestId) {
+        const cTestId = c.attributes?.['data-testid'] ?? c.attributes?.['data-test'];
+        return cTestId === candTestId;
+      }
+      // If id exists, check match on id
+      if (candidate.attributes?.['id']) {
+        return c.attributes?.['id'] === candidate.attributes?.['id'];
+      }
+      return c.tag === candidate.tag && c.role === candidate.role && c.accessibleName === candidate.accessibleName;
+    }).length;
+
+    const uniqueness = matchingCount === 1 ? 1.0 : matchingCount > 1 ? parseFloat((1 / matchingCount).toFixed(3)) : 0.0;
+    explanation.push(`Uniqueness U: ${uniqueness} (${matchingCount} matching element(s) in scope)`);
+
+    // 2. Identity Match I: Entity identity and affirmative token overlap
+    let identityMatch = candidate.accessibleName ? (originalSelector ? 0.3 : 0.8) : 0.3;
+    if (candidate.accessibleName) {
+      if (originalSelector) {
+        const origNorm = originalSelector.toLowerCase().replace(/[-_]/g, ' ');
+        const nameNorm = candidate.accessibleName.toLowerCase().replace(/[-_]/g, ' ');
+        const exactIdentityMatch = origNorm.includes(nameNorm) || nameNorm.includes(origNorm);
+
+        const originalIntent = semanticIntentGroup(origNorm);
+        const candidateIntent = semanticIntentGroup(nameNorm);
+        if (exactIdentityMatch) {
+          identityMatch = 1.0;
+          explanation.push('Identity Match I: 1.0 (Exact identity text match detected)');
+        } else if (originalIntent && candidateIntent && originalIntent === candidateIntent) {
+          identityMatch = 0.98;
+          explanation.push('Identity Match I: 0.98 (Equivalent semantic action intent detected)');
+        } else if (originalIntent && candidateIntent && originalIntent !== candidateIntent) {
+          const negativeIntents = new Set(['logout', 'log out', 'signout', 'sign out', 'cancel', 'close', 'dismiss', 'abort']);
+          const originalIsNegative = originalIntent.some((term) => negativeIntents.has(term));
+          const candidateIsNegative = candidateIntent.some((term) => negativeIntents.has(term));
+          if (originalIsNegative !== candidateIsNegative) {
+            identityMatch = 0.0;
+            explanation.push('Identity Match I: 0.0 (Conflicting semantic action intent detected)');
+          }
+        }
+
+        // Hard check: Contradictory semantics (submit vs cancel)
+        const positiveWords = ['submit', 'login', 'checkout', 'save', 'confirm', 'proceed', 'pay', 'order'];
+        const negativeWords = ['cancel', 'close', 'reset', 'abort', 'back', 'dismiss', 'delete'];
+
+        const origIsPositive = positiveWords.some((t) => origNorm.includes(t));
+        const candIsNegative = negativeWords.some((t) => nameNorm.includes(t));
+        const origIsNegative = negativeWords.some((t) => origNorm.includes(t));
+        const candIsPositive = positiveWords.some((t) => nameNorm.includes(t));
+
+        // Differentiating action token conflicts (e.g. continue shopping vs continue checkout)
+        const distinguishingPairs: Array<[string, string]> = [
+          ['shopping', 'checkout'],
+          ['cart', 'checkout'],
+          ['prev', 'next'],
+          ['previous', 'next'],
+          ['first', 'last'],
+          ['left', 'right'],
+          ['up', 'down'],
+          ['yes', 'no'],
+          ['approve', 'reject'],
+          ['accept', 'decline'],
+          ['enable', 'disable'],
+          ['open', 'close'],
+          ['edit', 'delete'],
+          ['create', 'delete'],
+          ['add', 'delete'],
+          ['remove', 'edit'],
+          ['modify', 'delete'],
+        ];
+
+        let hasDistinguishingConflict = false;
+        for (const [w1, w2] of distinguishingPairs) {
+          const origHasW1 = origNorm.includes(w1);
+          const origHasW2 = origNorm.includes(w2);
+          const candHasW1 = nameNorm.includes(w1);
+          const candHasW2 = nameNorm.includes(w2);
+          if (
+            (origHasW1 && !origHasW2 && candHasW2 && !candHasW1) ||
+            (origHasW2 && !origHasW1 && candHasW1 && !candHasW2)
+          ) {
+            hasDistinguishingConflict = true;
+            break;
+          }
+        }
+
+        if (identityMatch === 0.98 || identityMatch === 0.0) {
+          // Preserve the stronger semantic intent result above.
+        } else if (hasDistinguishingConflict) {
+          identityMatch = 0.1;
+          explanation.push(`Identity Match I: 0.1 (Conflicting action token intent detected)`);
+        } else if ((origIsPositive && candIsNegative) || (origIsNegative && candIsPositive)) {
+          identityMatch = 0.0;
+          explanation.push(`Identity Match I: 0.0 (Hard contradiction: target has opposing confirmation/cancellation semantics)`);
+        } else if (exactIdentityMatch) {
+          identityMatch = 1.0;
+        } else {
+          // Token overlap evaluating composite candidate identity (accessibleName, text, testid, id)
+          const candCompositeText = [
+            candidate.accessibleName ?? '',
+            candidate.text ?? '',
+            candidate.attributes['data-testid'] ?? candidate.attributes['data-test'] ?? '',
+            candidate.attributes['id'] ?? '',
+          ].join(' ').toLowerCase().replace(/[-_]/g, ' ');
+
+          const origWords = new Set(origNorm.split(/[^a-z0-9]+/).filter((w) => w.length > 2));
+          const candWords = new Set(candCompositeText.split(/[^a-z0-9]+/).filter((w) => w.length > 2));
+          if (origWords.size > 0 && candWords.size > 0) {
+            const intersection = [...origWords].filter((w) => candWords.has(w));
+            const overlap = intersection.length / Math.min(origWords.size, candWords.size);
+            if (overlap >= 0.5) {
+              identityMatch = 0.95;
+            } else if (overlap > 0) {
+              identityMatch = 0.85;
+            } else {
+              identityMatch = 0.0;
+              explanation.push(`Identity Match I: 0.0 (Zero token overlap or semantic correspondence with original selector)`);
+            }
+          } else {
+            identityMatch = 0.2;
+            explanation.push(`Identity Match I: 0.2 (Insufficient token information to prove identity)`);
+          }
+        }
+
+        // Semantic Role Alignment: If original explicitly specifies button vs link
+        const origWantsButton = /\bbutton\b/i.test(originalSelector) || /getByRole\(\s*['"]button['"]/i.test(originalSelector) || /#btn-/i.test(originalSelector);
+        const origWantsLink = /\b(link|a)\b/i.test(originalSelector) || /getByRole\(\s*['"]link['"]/i.test(originalSelector);
+
+        if (origWantsButton && (candidate.role === 'link' || candidate.tag === 'a') && candidate.role !== 'button') {
+          identityMatch = Math.max(0, identityMatch - 0.25);
+          explanation.push('Role Mismatch Penalty: -0.25 (Original selector requires button, candidate is link/anchor)');
+        } else if (origWantsLink && candidate.role === 'button' && candidate.tag !== 'a') {
+          identityMatch = Math.max(0, identityMatch - 0.25);
+          explanation.push('Role Mismatch Penalty: -0.25 (Original selector requires link, candidate is button)');
+        }
+      }
+    }
+    explanation.push(`Identity Match I: ${identityMatch}`);
+
+    // 3. Semantic Match M: getByRole / getByLabel priority over raw CSS
+    let semanticMatch = 0.4; // Base for raw HTML tag
+    if (candidate.role && candidate.accessibleName) {
+      semanticMatch = 1.0; // Priority: Role + Accessible Name
+    } else if (candidate.attributes['data-testid'] || candidate.attributes['data-test']) {
+      semanticMatch = 0.9; // Dedicated Test ID
+    } else if (candidate.attributes['placeholder'] || candidate.attributes['aria-label']) {
+      semanticMatch = 0.85;
+    }
+    explanation.push(`Semantic Match M: ${semanticMatch} (Role: ${candidate.role ?? 'none'})`);
+
+    // 4. Actionability A: Element is enabled and visible
+    const isDisabled = Boolean(candidate.attributes['disabled']) || candidate.attributes['aria-disabled'] === 'true';
+    const isHidden = candidate.attributes['hidden'] === 'true' || candidate.attributes['aria-hidden'] === 'true';
+    const actionability = isDisabled || isHidden ? 0.0 : 1.0;
+    explanation.push(`Actionability A: ${actionability} (Disabled: ${isDisabled}, Hidden: ${isHidden})`);
+
+    // 5. Historical Execution Reliability H: Neutral 0.5 baseline if unrecorded
+    const historicalReliability = historicalScore !== undefined
+      ? Math.max(0, Math.min(1.0, historicalScore))
+      : 0.5;
+    explanation.push(`Historical Execution Reliability H: ${historicalReliability}`);
+
+    // 6. Volatile Implementation Dependence D (Penalizes hashed classes and dynamic IDs)
+    let volatilePenalty = 0.0;
+    const id = candidate.attributes['id'] ?? '';
+    const classAttr = candidate.attributes['class'] ?? '';
+
+    // Check for random hex/hash IDs e.g. "id-a1b2c3d4", React useId ":r1:", or component IDs
+    if (
+      /^[0-9a-f]{8,}$/i.test(id) ||
+      /^[a-z]+-[0-9a-f]{4,}$/i.test(id) ||
+      /^:r[0-9a-z]+:$/i.test(id) ||
+      /^(ember|chakra|radix)-\d+/i.test(id)
+    ) {
+      volatilePenalty += 0.5;
+    }
+
+    // Check for CSS-in-JS hashed classes e.g. "css-1a2b3c" or "sc-xyz123"
+    if (/css-[a-z0-9]+/i.test(classAttr) || /sc-[a-z0-9]+/i.test(classAttr)) {
+      volatilePenalty += 0.4;
+    }
+
+    volatilePenalty = Math.min(1.0, volatilePenalty);
+    explanation.push(`Volatile Penalty D: ${volatilePenalty}`);
+
+    const candidateKind = candidate.role && candidate.accessibleName
+      ? 'getByRole'
+      : candidate.attributes['data-testid'] || candidate.attributes['data-test']
+        ? 'getByTestId'
+        : candidate.attributes['placeholder'] || candidate.attributes['aria-label']
+          ? 'getByLabel'
+          : candidate.text
+            ? 'getByText'
+            : 'locator';
+    const locatorUsage = projectContext?.locatorUsage;
+    const usageTotal = locatorUsage
+      ? Object.values(locatorUsage).reduce((sum, count) => sum + (typeof count === 'number' && count > 0 ? count : 0), 0)
+      : 0;
+    const conventionAlignment = usageTotal > 0
+      ? Math.max(0, Math.min(1, (locatorUsage?.[candidateKind] ?? 0) / usageTotal))
+      : projectContext?.preferredLocator && projectContext.preferredLocator !== 'unknown'
+        ? projectContext.preferredLocator === candidateKind ? 1 : 0
+        : 0.5;
+    // Keep convention influence deliberately small: observed project style can
+    // break a close tie, but never compensate for weak identity or uniqueness.
+    const conventionBonus = usageTotal > 0 || (projectContext?.preferredLocator && projectContext.preferredLocator !== 'unknown')
+      ? (conventionAlignment - 0.5) * 0.04
+      : 0;
+    explanation.push(`Project Convention C: ${conventionAlignment.toFixed(3)} (${candidateKind}${projectContext?.preferredLocator ? `; preferred ${projectContext.preferredLocator}` : ''}${usageTotal > 0 ? `; observed ${usageTotal}` : ''})`);
+
+    // Calculate final composite score S(L)
+    const rawScore =
+      weights.wU * uniqueness +
+      weights.wI * identityMatch +
+      weights.wM * semanticMatch +
+      weights.wA * actionability +
+      weights.wH * historicalReliability -
+      weights.wD * volatilePenalty +
+      conventionBonus;
+
+    const finalScore = Math.max(0, Math.min(1.0, parseFloat(rawScore.toFixed(3))));
+
+    // Intent Gate: If candidate has no token overlap or conflicting identity,
+    // cap the transformed score to strictly prevent false repairs on missing/unrelated actions.
+    if (identityMatch <= 0.1) {
+      explanation.push('Intent Gated: Zero/conflicting identity match caps transformed confidence to 0.05');
+      return {
+        score: Math.min(0.15, finalScore),
+        transformedScore: 0.05,
+        calibratedProbability: 0.05,
+        uniqueness,
+        matchCount: matchingCount,
+        identityMatch,
+        semanticMatch,
+        actionability,
+        historicalReliability,
+        historicalExecutionReliability: historicalReliability,
+        volatilePenalty,
+        conventionAlignment,
+        explanation,
+      };
+    }
+
+    // Transformed confidence score via logistic sigmoid scaling
+    const transformedScore = parseFloat((1 / (1 + Math.exp(-6 * (finalScore - 0.65)))).toFixed(3));
+
+    return {
+      score: finalScore,
+      transformedScore,
+      calibratedProbability: transformedScore, // Backward compatibility alias
+      uniqueness,
+      matchCount: matchingCount,
+      identityMatch,
+      semanticMatch,
+      actionability,
+      historicalReliability,
+      historicalExecutionReliability: historicalReliability,
+      volatilePenalty,
+      conventionAlignment,
+      explanation,
+    };
+  }
+}

package/src/trace/adapters/adapter-registry.ts

@@ -0,0 +1,49 @@
+import { TraceAdapter, ArchiveManifest } from './trace-adapter.js';
+import { V8TraceAdapter } from './v8-adapter.js';
+import { V4TraceAdapter } from './v4-adapter.js';
+import { V9TraceAdapter } from './v9-adapter.js';
+import { V10TraceAdapter } from './v10-adapter.js';
+import { UnknownTraceAdapter } from './unknown-adapter.js';
+
+export class TraceAdapterRegistry {
+  private static adapters: TraceAdapter[] = [
+    new V10TraceAdapter(),
+    new V9TraceAdapter(),
+    new V8TraceAdapter(),
+    new V4TraceAdapter(),
+  ];
+
+  private static fallbackAdapter = new UnknownTraceAdapter();
+
+  /**
+   * Registers a custom or extended trace adapter.
+   */
+  public static registerAdapter(adapter: TraceAdapter): void {
+    TraceAdapterRegistry.adapters.unshift(adapter);
+  }
+
+  /**
+   * Resolves the matching TraceAdapter for a given trace format version.
+   */
+  public static getAdapter(version: number): TraceAdapter {
+    for (const adapter of TraceAdapterRegistry.adapters) {
+      if (adapter.supportedFormatVersions.includes(version)) {
+        return adapter;
+      }
+    }
+    return TraceAdapterRegistry.fallbackAdapter;
+  }
+
+  /**
+   * Resolves the matching TraceAdapter for a given trace archive and sample lines.
+   */
+  public static resolveAdapter(manifest: ArchiveManifest, sampleLines: string[]): TraceAdapter {
+    for (const adapter of TraceAdapterRegistry.adapters) {
+      if (adapter.canParse(manifest, sampleLines)) {
+        return adapter;
+      }
+    }
+    return TraceAdapterRegistry.fallbackAdapter;
+  }
+}
+

package/src/trace/adapters/trace-adapter.ts

@@ -0,0 +1,28 @@
+import { DiagnosticContext } from '../../core/types/diagnostic-context.js';
+
+export interface ArchiveManifest {
+  archivePath: string;
+  entryNames: string[];
+  traceEntryName?: string | undefined;
+  networkEntryName?: string | undefined;
+  stacksEntryName?: string | undefined;
+}
+
+export interface AdapterValidationResult {
+  isValid: boolean;
+  errors: string[];
+  warnings: string[];
+}
+
+export interface TraceAdapter {
+  readonly adapterVersion: string;
+  readonly supportedFormatVersions: number[];
+  canParse(manifest: ArchiveManifest, sampleLines: string[]): boolean;
+  parse(
+    manifest: ArchiveManifest,
+    traceLines: string[],
+    networkLines: string[]
+  ): Promise<DiagnosticContext>;
+  validate(context: DiagnosticContext): AdapterValidationResult;
+}
+

package/src/trace/adapters/unknown-adapter.ts

@@ -0,0 +1,50 @@
+import { TraceAdapter, ArchiveManifest, AdapterValidationResult } from './trace-adapter.js';
+import { DiagnosticContext } from '../../core/types/diagnostic-context.js';
+import { VersionDetector } from '../version-detector.js';
+
+export class UnknownTraceAdapter implements TraceAdapter {
+  public readonly adapterVersion = '1.0.0-unsupported';
+  public readonly supportedFormatVersions: number[] = [];
+
+  public canParse(_manifest: ArchiveManifest, _sampleLines: string[]): boolean {
+    return true; // Catch-all fallback
+  }
+
+  public async parse(
+    _manifest: ArchiveManifest,
+    traceLines: string[],
+    _networkLines: string[]
+  ): Promise<DiagnosticContext> {
+    const versionInfo = VersionDetector.detectFromLines(traceLines);
+
+    return {
+      playwrightVersion: versionInfo.playwrightVersion ?? 'unknown',
+      traceFormatVersion: versionInfo.traceFormatVersion,
+      failedAction: {
+        callId: 'unknown',
+        action: 'unknown',
+        errorMessage: `Unsupported trace format version: ${versionInfo.traceFormatVersion}`,
+      },
+      snapshots: {},
+      networkEvents: [],
+      consoleEvents: [],
+      failureCategory: 'UNSUPPORTED_TRACE_FORMAT',
+      evidenceCompleteness: {
+        domAvailable: false,
+        networkAvailable: false,
+        sourceAvailable: false,
+      },
+    };
+  }
+
+  public validate(context: DiagnosticContext): AdapterValidationResult {
+    return {
+      isValid: false,
+      errors: [
+        `UNSUPPORTED_TRACE_FORMAT: Trace format version ${context.traceFormatVersion} is not supported by any active trace adapter. Engine strictly abstains from inventing unverified diagnostics.`,
+      ],
+      warnings: [],
+    };
+  }
+}
+

package/src/trace/adapters/v10-adapter.ts

@@ -0,0 +1,39 @@
+import { TraceAdapter, ArchiveManifest, AdapterValidationResult } from './trace-adapter.js';
+import { DiagnosticContext } from '../../core/types/diagnostic-context.js';
+import { TraceParser } from '../trace-parser.js';
+import { VersionDetector } from '../version-detector.js';
+
+export class V10TraceAdapter implements TraceAdapter {
+  public readonly adapterVersion = '1.0.0-v10';
+  public readonly supportedFormatVersions = [10];
+
+  public canParse(_manifest: ArchiveManifest, sampleLines: string[]): boolean {
+    const versionInfo = VersionDetector.detectFromLines(sampleLines);
+    return this.supportedFormatVersions.includes(versionInfo.traceFormatVersion);
+  }
+
+  public async parse(
+    _manifest: ArchiveManifest,
+    traceLines: string[],
+    networkLines: string[]
+  ): Promise<DiagnosticContext> {
+    const context = TraceParser.assembleDiagnosticContext(traceLines, networkLines);
+    return context;
+  }
+
+  public validate(context: DiagnosticContext): AdapterValidationResult {
+    const errors: string[] = [];
+    const warnings: string[] = [];
+
+    if (!context.failedAction.callId || context.failedAction.callId === 'unknown') {
+      warnings.push('Action callId could not be definitively extracted from modern v10 trace');
+    }
+
+    return {
+      isValid: errors.length === 0,
+      errors,
+      warnings,
+    };
+  }
+}
+

package/src/trace/adapters/v4-adapter.ts

@@ -0,0 +1,31 @@
+import { TraceAdapter, ArchiveManifest, AdapterValidationResult } from './trace-adapter.js';
+import { DiagnosticContext } from '../../core/types/diagnostic-context.js';
+import { TraceParser } from '../trace-parser.js';
+import { VersionDetector } from '../version-detector.js';
+
+/** Compatibility adapter for Playwright 1.32-era trace format v4. */
+export class V4TraceAdapter implements TraceAdapter {
+  public readonly adapterVersion = '1.0.0-v4';
+  public readonly supportedFormatVersions = [4];
+
+  public canParse(_manifest: ArchiveManifest, sampleLines: string[]): boolean {
+    const versionInfo = VersionDetector.detectFromLines(sampleLines);
+    return this.supportedFormatVersions.includes(versionInfo.traceFormatVersion);
+  }
+
+  public async parse(
+    _manifest: ArchiveManifest,
+    traceLines: string[],
+    networkLines: string[],
+  ): Promise<DiagnosticContext> {
+    return TraceParser.assembleDiagnosticContext(traceLines, networkLines);
+  }
+
+  public validate(context: DiagnosticContext): AdapterValidationResult {
+    const warnings: string[] = [];
+    if (!context.failedAction.callId || context.failedAction.callId === 'unknown') {
+      warnings.push('Action callId could not be definitively extracted from legacy v4 trace');
+    }
+    return { isValid: true, errors: [], warnings };
+  }
+}

package/src/trace/adapters/v8-adapter.ts

@@ -0,0 +1,42 @@
+import { TraceAdapter, ArchiveManifest, AdapterValidationResult } from './trace-adapter.js';
+import { DiagnosticContext } from '../../core/types/diagnostic-context.js';
+import { TraceParser } from '../trace-parser.js';
+import { VersionDetector } from '../version-detector.js';
+
+export class V8TraceAdapter implements TraceAdapter {
+  public readonly adapterVersion = '1.0.0-v8';
+  public readonly supportedFormatVersions = [7, 8];
+
+  public canParse(_manifest: ArchiveManifest, sampleLines: string[]): boolean {
+    const versionInfo = VersionDetector.detectFromLines(sampleLines);
+    return this.supportedFormatVersions.includes(versionInfo.traceFormatVersion);
+  }
+
+  public async parse(
+    _manifest: ArchiveManifest,
+    traceLines: string[],
+    networkLines: string[]
+  ): Promise<DiagnosticContext> {
+    const context = TraceParser.assembleDiagnosticContext(traceLines, networkLines);
+    context.traceFormatVersion = 8;
+    return context;
+  }
+
+  public validate(context: DiagnosticContext): AdapterValidationResult {
+    const errors: string[] = [];
+    const warnings: string[] = [];
+
+    if (!context.failedAction.callId || context.failedAction.callId === 'unknown') {
+      warnings.push('Action callId could not be definitively extracted from v8 trace');
+    }
+    if (context.networkEvents.length === 0) {
+      warnings.push('No network events parsed from v8 network stream');
+    }
+
+    return {
+      isValid: errors.length === 0,
+      errors,
+      warnings,
+    };
+  }
+}

package/src/trace/adapters/v9-adapter.ts

@@ -0,0 +1,39 @@
+import { TraceAdapter, ArchiveManifest, AdapterValidationResult } from './trace-adapter.js';
+import { DiagnosticContext } from '../../core/types/diagnostic-context.js';
+import { TraceParser } from '../trace-parser.js';
+import { VersionDetector } from '../version-detector.js';
+
+export class V9TraceAdapter implements TraceAdapter {
+  public readonly adapterVersion = '1.0.0-v9';
+  public readonly supportedFormatVersions = [9];
+
+  public canParse(_manifest: ArchiveManifest, sampleLines: string[]): boolean {
+    const versionInfo = VersionDetector.detectFromLines(sampleLines);
+    return this.supportedFormatVersions.includes(versionInfo.traceFormatVersion);
+  }
+
+  public async parse(
+    _manifest: ArchiveManifest,
+    traceLines: string[],
+    networkLines: string[]
+  ): Promise<DiagnosticContext> {
+    const context = TraceParser.assembleDiagnosticContext(traceLines, networkLines);
+    return context;
+  }
+
+  public validate(context: DiagnosticContext): AdapterValidationResult {
+    const errors: string[] = [];
+    const warnings: string[] = [];
+
+    if (!context.failedAction.action || context.failedAction.action === 'unknown') {
+      warnings.push('Action name was unknown in v9 format stream');
+    }
+
+    return {
+      isValid: errors.length === 0,
+      errors,
+      warnings,
+    };
+  }
+}
+