@sun-asterisk/sungen 3.2.34 → 3.3.0-alpha.2

package/src/contract/trace/snapshot-resolver.ts

@@ -0,0 +1,66 @@
+/**
+ * The snapshot that shows a call's target, rendered for replay (DOS-14.5; spike criterion 6).
+ *
+ * Playwright marks the element a call acted on with `__playwright_target__="<callId>"`. For an
+ * action that is the `input@` (v9: `action`) snapshot — the moment of the action; for a check the
+ * `after@` snapshot (the state it passed on). The order `input → before → after` is the spike's
+ * (R10: a child frame sometimes lacks one snapshot name; the fallback still found every target).
+ * No marked element in any snapshot → no target (identity `low`).
+ */
+import { createHash } from 'crypto';
+import type { ParsedTrace } from './trace-file-reader';
+import { renderSnapshot, RenderStats } from './snapshot-html-renderer';
+import { attrsOf, FrameSnapshot, isEl, isRef, kidsOf, SnapNode, SnapshotStore } from './snapshot-store';
+import type { TargetFacts } from './target-identity';
+
+export interface CallTarget {
+  callId: string;
+  snapshotKey: string;
+  html: string;
+  /** sha256 of the rendered HTML — the key a driver identity is cached under. */
+  snapshotSha256: string;
+  viewport: { width: number; height: number };
+  stats: RenderStats;
+  /** What already forces `low`, whatever the driver says. */
+  capReasons: string[];
+  facts: TargetFacts;
+}
+
+const ORDER = ['input', 'before', 'after'];
+
+/** `label[for]` texts of a snapshot, for the heuristic name of a labelled control. */
+function labelTexts(store: SnapshotStore, snap: FrameSnapshot): Map<string, string> {
+  const out = new Map<string, string>();
+  const stats = { refs: 0, brokenRefs: 0 };
+  const stack: Array<{ n: SnapNode; s: FrameSnapshot }> = [{ n: snap.html, s: snap }];
+  while (stack.length) {
+    let { n, s } = stack.pop()!;
+    if (isRef(n)) { const d = store.deref(n, s, stats); if (!d) continue; n = d.n; s = d.snap; }
+    if (!isEl(n)) continue;
+    const a = attrsOf(n);
+    if (n[0].toUpperCase() === 'LABEL' && a.for) out.set(a.for, store.textOf(n, s));
+    for (const k of kidsOf(n)) stack.push({ n: k, s });
+  }
+  return out;
+}
+
+export function resolveCallTarget(store: SnapshotStore, trace: ParsedTrace, callId: string): CallTarget | null {
+  for (const phase of ORDER) {
+    for (const snap of store.byKey.get(`${phase}@${callId}`) ?? []) {
+      const hit = store.findTarget(snap, callId);
+      if (!hit) continue;
+      const { html, stats } = renderSnapshot(store, snap, (sha1) => trace.readResource(sha1));
+      const capReasons: string[] = [];
+      if (stats.stylesheetsMissing > 0) capReasons.push(`stylesheet-missing(${stats.stylesheetsMissing})`);
+      if (stats.brokenRefs > 0) capReasons.push(`broken-snapshot-refs(${stats.brokenRefs})`);
+      const attrs = Object.fromEntries(Object.entries(attrsOf(hit.el)).filter(([k]) => !k.startsWith('__playwright_')));
+      const facts: TargetFacts = { tag: hit.el[0], attrs, text: store.textOf(hit.el, hit.snap) };
+      if (attrs.id) facts.labelText = labelTexts(store, snap).get(attrs.id);
+      return {
+        callId, snapshotKey: snap.key, html, snapshotSha256: createHash('sha256').update(html).digest('hex'),
+        viewport: snap.viewport, stats, capReasons, facts,
+      };
+    }
+  }
+  return null;
+}

package/src/contract/trace/snapshot-store.ts

@@ -0,0 +1,151 @@
+/**
+ * The frame snapshots of a trace, indexed the way Playwright's trace viewer indexes them, so a
+ * snapshot can be rebuilt as static HTML for identity replay (DOS-14.5; phase 07 criterion 6).
+ *
+ * A snapshot reuses unchanged subtrees of an EARLIER snapshot of the same frame as `[[ago, idx]]`
+ * references; `idx` counts nodes in post-order (children first, then the element), exactly as the
+ * viewer numbers them. A reference that points outside its frame's history is counted as broken —
+ * a broken replay caps identity at `low`, never guesses.
+ *
+ * Snapshot naming differs by format: v8 names it `input@call@12`, v9 gives `{callId, phase}` with
+ * phase `before | action | after`. Both are keyed here as `<before|input|after>@<callId>`.
+ */
+import type { LibraryPart } from './trace-file-reader';
+
+export type SnapNode = string | [[number, number]] | [string, Record<string, string>?, ...SnapNode[]];
+export interface FrameSnapshot {
+  key: string; callId: string; frameId: string; frameUrl: string; doctype?: string; html: SnapNode;
+  viewport: { width: number; height: number }; timestamp: number; isMainFrame: boolean;
+  resourceOverrides: Array<{ url: string; sha1?: string; ref?: number }>;
+  part: LibraryPart; index: number;
+}
+export interface RefStats { refs: number; brokenRefs: number }
+
+export const isRef = (n: unknown): n is [[number, number]] => Array.isArray(n) && Array.isArray(n[0]);
+export const isEl = (n: unknown): n is [string, Record<string, string>?, ...SnapNode[]] => Array.isArray(n) && typeof n[0] === 'string';
+export const attrsOf = (n: [string, Record<string, string>?, ...SnapNode[]]): Record<string, string> =>
+  (n[1] && typeof n[1] === 'object' && !Array.isArray(n[1]) ? n[1] : {}) as Record<string, string>;
+export const kidsOf = (n: [string, Record<string, string>?, ...SnapNode[]]): SnapNode[] => n.slice(2) as SnapNode[];
+
+const PHASE: Record<string, string> = { before: 'before', action: 'input', input: 'input', after: 'after' };
+
+function keyOf(s: Record<string, unknown>): string | null {
+  if (typeof s.snapshotName === 'string') return s.snapshotName;
+  if (typeof s.callId === 'string' && typeof s.phase === 'string' && PHASE[s.phase]) return `${PHASE[s.phase]}@${s.callId}`;
+  return null;
+}
+
+export class SnapshotStore {
+  readonly frames = new Map<string, FrameSnapshot[]>();
+  readonly byKey = new Map<string, FrameSnapshot[]>();
+  private nodeCache = new Map<FrameSnapshot, SnapNode[]>();
+
+  constructor(parts: LibraryPart[]) {
+    for (const part of parts) {
+      for (const e of part.events) {
+        if (e.type !== 'frame-snapshot' || !e.snapshot || typeof e.snapshot !== 'object') continue;
+        const s = e.snapshot as Record<string, unknown>;
+        const key = keyOf(s);
+        if (!key || typeof s.frameId !== 'string') continue;
+        const list = this.frames.get(s.frameId) ?? [];
+        const vp = (s.viewport ?? {}) as { width?: number; height?: number };
+        const snap: FrameSnapshot = {
+          key, callId: key.slice(key.indexOf('@') + 1), frameId: s.frameId, frameUrl: String(s.frameUrl ?? ''),
+          doctype: typeof s.doctype === 'string' ? s.doctype : undefined, html: s.html as SnapNode,
+          viewport: { width: Number(vp.width) || 1280, height: Number(vp.height) || 800 }, timestamp: Number(s.timestamp) || 0,
+          isMainFrame: s.isMainFrame !== false, resourceOverrides: Array.isArray(s.resourceOverrides) ? s.resourceOverrides as FrameSnapshot['resourceOverrides'] : [],
+          part, index: list.length,
+        };
+        list.push(snap);
+        this.frames.set(s.frameId, list);
+        this.byKey.set(key, [...(this.byKey.get(key) ?? []), snap]);
+      }
+    }
+  }
+
+  /** Non-reference nodes of a snapshot in post-order — Playwright's numbering for `[[ago, idx]]`. */
+  nodes(snap: FrameSnapshot): SnapNode[] {
+    const cached = this.nodeCache.get(snap);
+    if (cached) return cached;
+    const out: SnapNode[] = [];
+    const visit = (n: SnapNode): void => {
+      if (typeof n === 'string') out.push(n);
+      else if (isEl(n)) { kidsOf(n).forEach(visit); out.push(n); }
+    };
+    visit(snap.html);
+    this.nodeCache.set(snap, out);
+    return out;
+  }
+
+  /** Follow references to a concrete node, or null (counted as broken). */
+  deref(n: SnapNode, snap: FrameSnapshot, stats: RefStats): { n: SnapNode; snap: FrameSnapshot } | null {
+    let cur = n;
+    let at = snap;
+    for (let guard = 0; isRef(cur) && guard < 10_000; guard++) {
+      const [ago, idx] = cur[0];
+      const list = this.frames.get(at.frameId) ?? [];
+      const target = list[at.index - ago];
+      if (!Number.isInteger(ago) || ago < 0 || !target) { stats.brokenRefs++; return null; }
+      const nodes = this.nodes(target);
+      if (!Number.isInteger(idx) || idx < 0 || idx >= nodes.length) { stats.brokenRefs++; return null; }
+      cur = nodes[idx];
+      at = target;
+      stats.refs++;
+    }
+    return isRef(cur) ? null : { n: cur, snap: at };
+  }
+
+  /** The element Playwright marked as the target of `callId` in this snapshot, if any. */
+  findTarget(snap: FrameSnapshot, callId: string): { el: [string, Record<string, string>?, ...SnapNode[]]; snap: FrameSnapshot } | null {
+    const stats: RefStats = { refs: 0, brokenRefs: 0 };
+    const stack: Array<{ n: SnapNode; snap: FrameSnapshot }> = [{ n: snap.html, snap }];
+    while (stack.length) {
+      let { n, snap: at } = stack.pop()!;
+      if (isRef(n)) { const d = this.deref(n, at, stats); if (!d) continue; n = d.n; at = d.snap; }
+      if (!isEl(n)) continue;
+      // v8 marks the target with its call id; v9 snapshots belong to one call and mark it with ''.
+      const mark = attrsOf(n).__playwright_target__;
+      if (mark === callId || (mark === '' && snap.callId === callId)) return { el: n, snap: at };
+      for (const k of kidsOf(n)) stack.push({ n: k, snap: at });
+    }
+    return null;
+  }
+
+  /** The visible text under a node (references resolved), whitespace collapsed. */
+  textOf(n: SnapNode, snap: FrameSnapshot): string {
+    const stats: RefStats = { refs: 0, brokenRefs: 0 };
+    const out: string[] = [];
+    const visit = (x: SnapNode, at: FrameSnapshot): void => {
+      if (isRef(x)) { const d = this.deref(x, at, stats); if (d) visit(d.n, d.snap); return; }
+      if (typeof x === 'string') { out.push(x); return; }
+      if (isEl(x) && !/^(SCRIPT|STYLE|NOSCRIPT|TEMPLATE)$/i.test(x[0])) kidsOf(x).forEach((k) => visit(k, at));
+    };
+    visit(n, snap);
+    return out.join(' ').replace(/\s+/g, ' ').trim();
+  }
+
+  /** The stylesheet body for `href` as the page had it at this snapshot: override first, then network. */
+  stylesheetSha1(snap: FrameSnapshot, href: string): string | null {
+    let abs: string;
+    try { abs = new URL(href, snap.frameUrl).href.replace(/#.*$/, ''); } catch { return null; }
+    const list = this.frames.get(snap.frameId) ?? [];
+    let idx = snap.index;
+    for (let guard = 0; guard < 10_000 && list[idx]; guard++) {
+      const o = list[idx].resourceOverrides.find((x) => x.url === abs);
+      if (!o) break;
+      if (o.sha1) return o.sha1;
+      if (typeof o.ref !== 'number') break;
+      idx -= o.ref;
+    }
+    let same: string | null = null;
+    let other: string | null = null;
+    for (const r of snap.part.network) {
+      const s = (r.snapshot ?? {}) as { request?: { url?: string; method?: string }; response?: { status?: number; content?: { _sha1?: string; _file?: string } }; _monotonicTime?: number; _frameref?: string };
+      const body = s.response?.content?._sha1 ?? s.response?.content?._file; // v8: sha1 · v9: resources/<sha1>.<ext>
+      if (typeof s._monotonicTime === 'number' && s._monotonicTime >= snap.timestamp) continue;
+      if (s.request?.url !== abs || s.request?.method !== 'GET' || s.response?.status === 304 || !body) continue;
+      if (s._frameref === snap.frameId) same = body; else other = body;
+    }
+    return same ?? other;
+  }
+}

package/src/contract/trace/target-identity.ts

@@ -0,0 +1,104 @@
+/**
+ * Who an action or a check was aimed at (DOS-14.5, SPI §4.5 `traceIdentity`).
+ *
+ * The identity of a target is role + accessible name from the RUNTIME's own accessibility engine:
+ * `@sungen/driver-ui` replays the snapshot in a real browser (Playwright `ariaSnapshot` +
+ * `getByRole`) through the `traceIdentity` slot, with `identityConfidence: high | low`. Core
+ * cannot run a browser; its own reading of the snapshot (below) is a HEURISTIC and therefore
+ * always `low` — and `low` is never `match` (red-team #4).
+ *
+ * `high` also needs: the page's stylesheets all found (G1), no broken snapshot reference, a semantic
+ * role with a non-empty name, and role+name resolving back to exactly the marked element — or,
+ * when it does not (G3, ~12% of actions: "Add to cart" ×34), a named scope (row, landmark, dialog)
+ * inside which it does.
+ */
+export type IdentityConfidence = 'high' | 'low';
+export interface IdentityScope { role: string; name: string }
+
+export interface TargetIdentity {
+  role: string;
+  name: string;
+  level?: number;
+  scope?: IdentityScope;
+  identityConfidence: IdentityConfidence;
+  reasons: string[];
+  source: 'driver' | 'heuristic';
+}
+
+/** One snapshot to replay. `capReasons` are what core already knows forces `low` (missing CSS…). */
+export interface TraceIdentityRequest {
+  key: string;
+  html: string;
+  viewport: { width: number; height: number };
+  targetSelector: string;
+  capReasons: string[];
+}
+export interface TraceIdentityInput { requests: TraceIdentityRequest[] }
+export interface TraceIdentityResult {
+  key: string; role: string; name: string; level?: number; scope?: IdentityScope;
+  identityConfidence: IdentityConfidence; reasons: string[];
+}
+export interface TraceIdentityOutput {
+  resolver: string;
+  /** The browser build that judged every result (e.g. `chromium 143.0.7499.4`), kept per cache entry. */
+  browser: string;
+  results: TraceIdentityResult[];
+  /** Requests the replay page attempted (all blocked). Reported, never trusted for anything. */
+  blockedRequests?: number;
+}
+export type TraceIdentityResolver = (input: TraceIdentityInput) => Promise<TraceIdentityOutput>;
+
+/** What core can read off the snapshot about the marked element. */
+export interface TargetFacts { tag: string; attrs: Record<string, string>; text: string; labelText?: string }
+
+const INPUT_ROLE: Record<string, string> = {
+  checkbox: 'checkbox', radio: 'radio', submit: 'button', button: 'button', reset: 'button', image: 'button',
+  search: 'searchbox', number: 'spinbutton', range: 'slider',
+};
+
+function heuristicRole(f: TargetFacts): string {
+  if (f.attrs.role) return f.attrs.role.split(/\s+/)[0].toLowerCase();
+  const tag = f.tag.toUpperCase();
+  if (tag === 'A' && f.attrs.href !== undefined) return 'link';
+  if (tag === 'BUTTON') return 'button';
+  if (tag === 'INPUT') return INPUT_ROLE[(f.attrs.type || 'text').toLowerCase()] ?? 'textbox';
+  if (tag === 'SELECT') return 'combobox';
+  if (tag === 'TEXTAREA') return 'textbox';
+  if (/^H[1-6]$/.test(tag)) return 'heading';
+  if (tag === 'IMG') return 'img';
+  return 'generic';
+}
+
+/** Core's own reading of the snapshot — never better than `low`. */
+export function heuristicIdentity(f: TargetFacts | null, why: string): TargetIdentity {
+  if (!f) return { role: 'generic', name: '', identityConfidence: 'low', reasons: [why, 'no-target-in-snapshot'], source: 'heuristic' };
+  const role = heuristicRole(f);
+  const named = role === 'button' || role === 'link' || role === 'heading';
+  const name = f.attrs['aria-label'] || f.labelText || (named ? f.text : '') || f.attrs.placeholder || f.attrs.alt || f.attrs.title || '';
+  const level = /^H([1-6])$/i.exec(f.tag)?.[1];
+  return { role, name: name.replace(/\s+/g, ' ').trim(), ...(level ? { level: Number(level) } : {}), identityConfidence: 'low', reasons: [why], source: 'heuristic' };
+}
+
+const RESULT_KEYS = new Set(['key', 'role', 'name', 'level', 'scope', 'identityConfidence', 'reasons']);
+const isObj = (v: unknown): v is Record<string, unknown> => !!v && typeof v === 'object' && !Array.isArray(v);
+/** Bounded strings: an identity is a role and a name, never a payload. */
+const str = (v: unknown, max: number): v is string => typeof v === 'string' && v.length <= max;
+const ROLE_MAX = 64;
+const NAME_MAX = 1000;
+
+/** The only resolver whose answers the identity cache keeps (driver-ui's Playwright replay). */
+export const TRUSTED_RESOLVER = /^driver-ui\/playwright-aria@\d+$/;
+
+/** A resolver's result, checked strictly (unknown keys rejected) — null when it is not well-formed. */
+export function validIdentityResult(raw: unknown): TraceIdentityResult | null {
+  if (!isObj(raw) || Object.keys(raw).some((k) => !RESULT_KEYS.has(k))) return null;
+  const { key, role, name, level, scope, identityConfidence, reasons } = raw;
+  if (!str(key, 128) || !str(role, ROLE_MAX) || !str(name, NAME_MAX)) return null;
+  if (identityConfidence !== 'high' && identityConfidence !== 'low') return null;
+  if (!Array.isArray(reasons) || reasons.length > 20 || !reasons.every((r) => str(r, 300))) return null;
+  if (level !== undefined && !(Number.isInteger(level) && (level as number) >= 1 && (level as number) <= 6)) return null;
+  if (scope !== undefined && !(isObj(scope) && str(scope.role, ROLE_MAX) && str(scope.name, NAME_MAX) && Object.keys(scope).length === 2)) return null;
+  // `high` with a reason is a contradiction: a reason is what makes an identity low.
+  if (identityConfidence === 'high' && reasons.length) return null;
+  return { key, role, name, ...(level !== undefined ? { level: level as number } : {}), ...(scope ? { scope: scope as unknown as IdentityScope } : {}), identityConfidence, reasons: reasons as string[] };
+}

package/src/contract/trace/test-step-join.ts

@@ -0,0 +1,104 @@
+/**
+ * Join the test runner's steps (test.trace) with the browser calls (<N>-trace.trace) — phase 07
+ * criterion 2, proven 114/114 on a real app. Up to format 9 a library call's `stepId` is the runner
+ * step's `callId`; from format 10 (Playwright 1.64) the two share ONE id and `stepId` is gone, so the
+ * call's own `callId` is the step. Walking the runner's `parentId` chain says where the call ran:
+ *
+ *   body       the test function itself, with the path of enclosing `test.step` titles
+ *   hook       a user `beforeEach` / `afterEach` (stage setup | teardown)
+ *   fixture    a fixture's setup or teardown (`Fixture "signedInPage"`)
+ *   runner     the runner's own Before/After Hooks plumbing (browser launch, context close)
+ *
+ * Only body and user `beforeEach` calls are the test's behaviour; fixtures and teardown are
+ * environment, kept apart so a shared fixture cannot leak into every test's contract.
+ */
+import type { ParsedTrace, StackFrame, TraceEvent } from './trace-file-reader';
+
+export interface RunnerStep {
+  id: string; parentId?: string; method: string; title: string;
+  params: Record<string, unknown>; stack: StackFrame[]; failed: boolean;
+}
+
+export type CallPhase =
+  | { phase: 'body'; stepPath: string[] }
+  | { phase: 'hook'; stage: 'setup' | 'teardown'; name: string }
+  | { phase: 'fixture'; stage: 'setup' | 'teardown'; name: string }
+  | { phase: 'runner'; stage: 'setup' | 'teardown'; name: string }
+  | { phase: 'unjoined' };
+
+export interface JoinedCall {
+  part: string; callId: string; class: string; method: string;
+  params: Record<string, unknown>; stepId?: string; where: CallPhase; failed: boolean; startTime: number;
+}
+
+const str = (v: unknown): string => (typeof v === 'string' ? v : '');
+const RUNNER_HOOKS = /^(Before Hooks|After Hooks|Worker Cleanup)$/;
+
+function stackOf(e: TraceEvent): StackFrame[] {
+  const raw = Array.isArray(e.stack) ? e.stack : [];
+  return raw.filter((f): f is Record<string, unknown> => !!f && typeof f === 'object')
+    .map((f) => ({ file: str(f.file), line: Number(f.line) || 0, column: Number(f.column) || 0 }));
+}
+
+export function indexRunnerSteps(runner: TraceEvent[]): Map<string, RunnerStep> {
+  const steps = new Map<string, RunnerStep>();
+  for (const e of runner) {
+    const id = str(e.callId);
+    if (e.type === 'before' && id) {
+      steps.set(id, {
+        id, parentId: str(e.parentId) || undefined, method: str(e.method), title: str(e.title),
+        params: (e.params && typeof e.params === 'object' ? e.params : {}) as Record<string, unknown>, stack: stackOf(e), failed: false,
+      });
+    }
+    if (e.type === 'after' && steps.has(id) && e.error) steps.get(id)!.failed = true;
+  }
+  return steps;
+}
+
+/** The runner steps from `id` up to the root (self first). Cycles end the walk. */
+export function ancestry(steps: Map<string, RunnerStep>, id: string): RunnerStep[] {
+  const chain: RunnerStep[] = [];
+  const seen = new Set<string>();
+  for (let cur = steps.get(id); cur && !seen.has(cur.id); cur = cur.parentId ? steps.get(cur.parentId) : undefined) {
+    seen.add(cur.id);
+    chain.push(cur);
+  }
+  return chain;
+}
+
+export function classifyStep(steps: Map<string, RunnerStep>, stepId: string): CallPhase {
+  const chain = ancestry(steps, stepId);
+  if (!chain.length) return { phase: 'unjoined' };
+  const root = chain[chain.length - 1];
+  const stage = root.method === 'hook' && root.title === 'After Hooks' ? 'teardown' : 'setup';
+  const fixture = chain.find((s) => s.method === 'fixture');
+  if (fixture) return { phase: 'fixture', stage, name: fixture.title.replace(/^Fixture "(.*)"$/, '$1') };
+  const userHook = chain.find((s) => s.method === 'hook' && !RUNNER_HOOKS.test(s.title));
+  if (userHook) return { phase: 'hook', stage, name: userHook.title };
+  if (root.method === 'hook') return { phase: 'runner', stage, name: root.title };
+  return { phase: 'body', stepPath: chain.filter((s) => s.method === 'test.step').map((s) => s.title).reverse() };
+}
+
+/** Is this phase the test's own behaviour (body, or a user `beforeEach`)? */
+export const isBehaviour = (w: CallPhase): boolean => w.phase === 'body' || (w.phase === 'hook' && w.stage === 'setup');
+
+/** Every library call, joined to its runner step, in start order across parts. */
+export function joinCalls(trace: ParsedTrace): { steps: Map<string, RunnerStep>; calls: JoinedCall[] } {
+  const steps = indexRunnerSteps(trace.runner);
+  const calls: JoinedCall[] = [];
+  for (const part of trace.library) {
+    const failed = new Set(part.events.filter((e) => e.type === 'after' && e.error).map((e) => str(e.callId)));
+    for (const e of part.events) {
+      if (e.type !== 'before') continue;
+      const callId = str(e.callId);
+      const stepId = str(e.stepId) || (part.version >= 10 ? callId : '') || undefined;
+      calls.push({
+        part: part.name, callId, class: str(e.class), method: str(e.method),
+        params: (e.params && typeof e.params === 'object' ? e.params : {}) as Record<string, unknown>,
+        stepId, where: stepId ? classifyStep(steps, stepId) : { phase: 'unjoined' }, failed: failed.has(callId), startTime: Number(e.startTime) || 0,
+      });
+    }
+  }
+  calls.sort((a, b) => a.startTime - b.startTime);
+  return { steps, calls };
+}

package/src/contract/trace/trace-binding.ts

@@ -0,0 +1,56 @@
+/**
+ * May THIS trace speak for THIS test's final attempt? (DOS-14.6, red-team #5; phase 07 criterion 5.)
+ * A good trace of another test, of the same test from another run, or from before the contract
+ * changed is the "green by swap" path — every link below must hold:
+ *
+ *   run record    the attempt (testId, retry) is in sungen's own record of the run, passed
+ *   bytes         sha256(trace.zip) equals what the record wrote at the end of that run
+ *   code          sha256 of the test file NOW equals the hash the record took at run start
+ *   title         every library part says `<file>:<line> › … › <title>` of exactly this test
+ *   clock         the trace started inside the attempt's window (±2 s)
+ *   fresh         the trace is newer than the .feature and the lock it is asked to prove
+ */
+import { createHash } from 'crypto';
+import * as fs from 'fs';
+import * as path from 'path';
+import type { ParsedTrace } from './trace-file-reader';
+import type { RunRecord } from './trace-run-record';
+import type { ReportResult, ReportTest } from './select-final-attempt';
+
+export interface BindingInput {
+  projectRoot: string;
+  test: ReportTest;
+  result: ReportResult;
+  record: RunRecord;
+  trace: ParsedTrace;
+  /** Epoch ms: the newest mtime of the unit's .feature files and lock. */
+  notBefore: number;
+}
+export type Binding = { ok: true; specFile: string } | { ok: false; reason: string };
+
+const CLOCK_SLACK_MS = 2_000;
+
+export function bindTrace(i: BindingInput): Binding {
+  const fail = (reason: string): Binding => ({ ok: false, reason });
+  const attempt = i.record.attempts.find((a) => a.testId === i.test.testId && a.retry === i.result.retry);
+  if (!attempt) return fail(`run ${i.record.runId} has no record of this attempt (retry ${i.result.retry}) — the trace is not bound to a sungen run`);
+  if (attempt.status !== 'passed') return fail(`the run record says this attempt ${attempt.status}`);
+  if (!attempt.trace || attempt.trace.sha256 !== i.trace.sha256) {
+    return fail('this is not the trace the run recorded (sha256 differs) — swapped or edited after the run');
+  }
+  const specPath = path.join(i.projectRoot, attempt.file);
+  let now: string;
+  try { now = createHash('sha256').update(fs.readFileSync(specPath)).digest('hex'); } catch { return fail(`the test file ${attempt.file} is gone`); }
+  if (i.record.specs[attempt.file] !== now) return fail(`the test file ${attempt.file} changed since the run — re-run it`);
+  const prefix = `${i.test.file}:${i.test.line} › `;
+  if (!i.trace.titles.length) return fail('the trace names no test (no title in its header)');
+  const other = i.trace.titles.find((t) => !(t.startsWith(prefix) && t.endsWith(` › ${i.test.title}`)));
+  if (other) return fail(`the trace belongs to another test ("${other}")`);
+  const start = Date.parse(i.result.startTime);
+  const wall = i.trace.wallTime;
+  if (typeof wall !== 'number' || Number.isNaN(start) || wall < start - CLOCK_SLACK_MS || wall > start + i.result.duration + CLOCK_SLACK_MS) {
+    return fail('the trace was not recorded during this attempt (clock window)');
+  }
+  if (wall < i.notBefore) return fail('the trace is older than the .feature or the lock it should prove (stale) — re-run the test');
+  return { ok: true, specFile: attempt.file };
+}

package/src/contract/trace/trace-file-reader.ts

@@ -0,0 +1,133 @@
+/**
+ * One Playwright trace.zip → its parsed parts, after the zip limits and the format-version gate
+ * (DOS-14.6, DOS-14.7). Nothing past this point sees a trace that was not accepted here.
+ *
+ *   test.trace            the test runner's steps (test.step, hooks, fixtures, expect, pw:api)
+ *   <N>-trace.trace       a library part: the browser calls, frame snapshots, logs
+ *   <N>-trace.network     resources (stylesheets inlined into a replayed snapshot come from here)
+ *   <N>-trace.stacks      call id → source frames (`file:line` of an opaque step)
+ *   resources/<sha1>      resource bodies
+ *
+ * Every part that has a header (test.trace and each library part) must declare a supported version;
+ * a part without one is refused. Every JSONL line must parse — a line that does not is never skipped.
+ */
+import { createHash } from 'crypto';
+import * as fs from 'fs';
+import { openZip, ZipArchive } from './trace-zip-reader';
+import { SUPPORTED_TRACE_VERSIONS, traceZipLimits, TraceRejected, TraceZipLimits } from './trace-zip-limits';
+
+export type TraceEvent = { type: string } & Record<string, unknown>;
+export interface StackFrame { file: string; line: number; column: number }
+/**
+ * One library part. `version` is its declared format (already accepted by the gate); `stacks` is
+ * keyed by call id — v8/v9 wrote a call NUMBER (`11` → `call@11`, Playwright's legacy id), v10 the
+ * call id itself, which it shares with the runner step (`ulgt@50`).
+ */
+export interface LibraryPart { name: string; version: number; events: TraceEvent[]; network: TraceEvent[]; stacks: Map<string, StackFrame[]> }
+
+export interface ParsedTrace {
+  label: string;
+  sha256: string;
+  versions: Array<{ part: string; version: unknown }>;
+  runner: TraceEvent[];
+  library: LibraryPart[];
+  /** `wallTime` (epoch ms) of the runner's header: when the attempt started. */
+  wallTime: number | undefined;
+  /** `title` of every library part's header: `<file>:<line> › <describe…> › <test title>`. */
+  titles: string[];
+  /** A resource body by sha1 (v8) or entry name `resources/<sha1>.<ext>` (v9); null when absent. */
+  readResource(ref: string): string | null;
+}
+
+const CALL_ID = /^[\w@.:-]{1,128}$/;
+
+function parseJsonl(zip: ZipArchive, name: string): TraceEvent[] {
+  const out: TraceEvent[] = [];
+  zip.readText(name).split('\n').forEach((line, i) => {
+    if (!line.trim()) return;
+    let v: unknown;
+    try { v = JSON.parse(line); } catch { throw new TraceRejected('trace.malformed', `${name} line ${i + 1} is not JSON`); }
+    if (!v || typeof v !== 'object' || Array.isArray(v) || typeof (v as { type?: unknown }).type !== 'string') {
+      throw new TraceRejected('trace.malformed', `${name} line ${i + 1} is not a trace event`);
+    }
+    // Call ids end up inside a CSS selector of the replay (`[__playwright_target__="…"]`).
+    const e = v as Record<string, unknown>;
+    const snap = e.snapshot && typeof e.snapshot === 'object' ? (e.snapshot as Record<string, unknown>).callId : undefined;
+    for (const id of [e.callId, e.stepId, e.parentId, snap]) {
+      if (id !== undefined && (typeof id !== 'string' || !CALL_ID.test(id))) throw new TraceRejected('trace.malformed', `${name} line ${i + 1}: ${JSON.stringify(String(id)).slice(0, 40)} is not a call id`);
+    }
+    out.push(v as TraceEvent);
+  });
+  return out;
+}
+
+function parseStacks(zip: ZipArchive, name: string): Map<string, StackFrame[]> {
+  const out = new Map<string, StackFrame[]>();
+  if (!zip.has(name)) return out;
+  let doc: { files?: unknown; stacks?: unknown };
+  try { doc = JSON.parse(zip.readText(name)); } catch { throw new TraceRejected('trace.malformed', `${name} is not JSON`); }
+  const files = Array.isArray(doc.files) ? doc.files.map(String) : [];
+  for (const row of Array.isArray(doc.stacks) ? doc.stacks : []) {
+    if (!Array.isArray(row) || !Array.isArray(row[1])) continue;
+    const id = typeof row[0] === 'number' ? `call@${row[0]}` : row[0];
+    if (typeof id !== 'string' || !CALL_ID.test(id)) continue;
+    const frames = (row[1] as unknown[]).filter(Array.isArray).map((f) => {
+      const [fileIdx, line, column] = f as number[];
+      return { file: files[fileIdx] ?? '', line: Number(line) || 0, column: Number(column) || 0 };
+    });
+    out.set(id, frames);
+  }
+  return out;
+}
+
+const headerOf = (events: TraceEvent[]): TraceEvent | undefined => events.find((e) => e.type === 'context-options');
+
+export function readTraceBuffer(buf: Buffer, label: string, limits: TraceZipLimits = traceZipLimits()): ParsedTrace {
+  const zip = openZip(buf, limits);
+  if (!zip.has('test.trace')) throw new TraceRejected('trace.malformed', 'no test.trace — not a Playwright Test trace (runner steps are required)');
+  const runner = parseJsonl(zip, 'test.trace');
+  const library: LibraryPart[] = zip.names().filter((n) => /^\d+-trace\.trace$/.test(n)).sort().map((n) => {
+    const base = n.replace(/\.trace$/, '');
+    const events = parseJsonl(zip, n);
+    const version = headerOf(events)?.version;
+    return {
+      name: n,
+      version: typeof version === 'number' ? version : NaN, // a non-number is refused just below
+      events,
+      network: zip.has(`${base}.network`) ? parseJsonl(zip, `${base}.network`) : [],
+      stacks: parseStacks(zip, `${base}.stacks`),
+    };
+  });
+  const versions = [{ part: 'test.trace', version: headerOf(runner)?.version }, ...library.map((l) => ({ part: l.name, version: headerOf(l.events)?.version }))];
+  const bad = versions.filter((v) => typeof v.version !== 'number' || !SUPPORTED_TRACE_VERSIONS.has(v.version));
+  if (bad.length) {
+    throw new TraceRejected('trace.version-unsupported',
+      `${bad.map((v) => `${v.part}=${v.version === undefined ? 'missing' : JSON.stringify(v.version)}`).join(', ')} (supported: ${[...SUPPORTED_TRACE_VERSIONS].join(', ')})`);
+  }
+  const head = headerOf(runner);
+  const cache = new Map<string, string | null>();
+  return {
+    label,
+    sha256: createHash('sha256').update(buf).digest('hex'),
+    versions,
+    runner,
+    library,
+    wallTime: typeof head?.wallTime === 'number' ? head.wallTime : undefined,
+    titles: library.map((l) => headerOf(l.events)?.title).filter((t): t is string => typeof t === 'string'),
+    readResource(ref: string): string | null {
+      // v8 names a resource by its sha1; v9 by its entry, `resources/<sha1>.<ext>`.
+      const name = ref.replace(/^resources\//, '');
+      if (!/^[A-Za-z0-9_-][A-Za-z0-9._-]*$/.test(name)) return null;
+      if (!cache.has(name)) cache.set(name, zip.has(`resources/${name}`) ? zip.readText(`resources/${name}`) : null);
+      return cache.get(name) ?? null;
+    },
+  };
+}
+
+/** Read a trace from disk: a regular file, size-checked BEFORE it is read into memory. */
+export function readTraceFile(file: string, limits: TraceZipLimits = traceZipLimits()): ParsedTrace {
+  const st = fs.statSync(file);
+  if (!st.isFile()) throw new TraceRejected('zip.malformed', `${file} is not a regular file`);
+  if (st.size > limits.maxZipBytes) throw new TraceRejected('zip.too-large', `${st.size} B > ${limits.maxZipBytes}`);
+  return readTraceBuffer(fs.readFileSync(file), file, limits);
+}