@sun-asterisk/sungen 3.2.35 → 3.3.0-alpha.10

package/src/contract/trace/snapshot-html-renderer.ts

@@ -0,0 +1,136 @@
+/**
+ * A frame snapshot → static, INERT HTML for identity replay (DOS-14.5, DOS-14.7). Port of the
+ * phase 07 spike renderer (refs resolved per frame; 1684 refs, 0 broken on the real app).
+ *
+ *   state     what the viewer's in-page script restores is applied statically (JS is off in the
+ *             replay): input values, checked / selected, open dialogs and popovers
+ *   CSS       stylesheets are INLINED from the trace's own resources (G1). A sheet that cannot be
+ *             found is counted: without the page's CSS, accessible names built from `display`
+ *             spacing or `::before` glyphs come out wrong (3/89 and 9/27 in the spike), so a
+ *             missing sheet caps identity at `low`
+ *   inert     no scripts, no `on*` handlers, no URL-bearing attribute, CSS `url()` / `@import`
+ *             stripped, a CSP meta that forbids every fetch, `<base>` / refresh dropped
+ */
+import { attrsOf, FrameSnapshot, isEl, isRef, kidsOf, RefStats, SnapNode, SnapshotStore } from './snapshot-store';
+
+export interface RenderStats extends RefStats { stylesheets: number; stylesheetsMissing: number }
+export interface RenderedSnapshot { html: string; stats: RenderStats }
+
+const AUTO_CLOSING = new Set(['AREA', 'BASE', 'BR', 'COL', 'COMMAND', 'EMBED', 'HR', 'IMG', 'INPUT', 'KEYGEN', 'LINK', 'MENUITEM', 'META', 'PARAM', 'SOURCE', 'TRACK', 'WBR']);
+const URL_ATTRS = new Set(['src', 'srcset', 'href', 'action', 'formaction', 'poster', 'data', 'background', 'xlink:href', 'ping', 'longdesc', 'cite', 'manifest', 'codebase', 'archive', 'lowsrc', 'dynsrc', 'srcdoc', 'imagesrcset']);
+export const REPLAY_CSP = "default-src 'none'; style-src 'unsafe-inline'; img-src 'none'; font-src 'none'; media-src 'none'; frame-src 'none'; child-src 'none'; object-src 'none'; form-action 'none'; base-uri 'none'; connect-src 'none'; script-src 'none'";
+
+const escapeHtml = (s: string): string => s.replace(/&/g, '&amp;').replace(/</g, '&lt;').replace(/>/g, '&gt;');
+const escapeAttr = (s: string): string => String(s).replace(/&/g, '&amp;').replace(/"/g, '&quot;').replace(/</g, '&lt;').replace(/>/g, '&gt;');
+/** A tag name that is only a name — anything else in a trace is markup smuggled into the name. */
+const TAG_NAME = /^[A-Za-z][A-Za-z0-9-]*$/;
+
+/** CSS escapes decoded (`\75 ` → `u`, `\r` → `r`) and comments removed — what the CSS parser sees. */
+const decodeCss = (css: string): string => css
+  .replace(/\\([0-9a-fA-F]{1,6})[ \t\n\r\f]?/g, (_m, hex: string) => {
+    const cp = parseInt(hex, 16);
+    return cp > 0 && cp <= 0x10ffff ? String.fromCodePoint(cp) : '�';
+  })
+  .replace(/\\([^\n0-9a-fA-F])/g, '$1')
+  .replace(/\/\*[\s\S]*?\*\//g, '');
+const FETCHING = /url\s*\(|@import|image-set\s*\(/i;
+
+const stripFetches = (css: string): string => css
+  .replace(/@import[^;]*;?/gi, '')
+  .replace(/(-webkit-)?image-set\((?:[^()]|\([^)]*\))*\)/gi, 'none')
+  .replace(/url\(\s*(?:"[^"]*"|'[^']*'|[^)]*)\s*\)/gi, 'none');
+
+/**
+ * CSS with every fetch removed. A URL hidden behind escapes or comments (`u\72l(`, `@\69mport`) is
+ * caught on the decoded text, and then the DECODED text is what is kept; CSS that hides nothing
+ * stays byte-identical (icon-font `content: "\f101"` escapes matter for accessible names, R4).
+ */
+export function sanitizeCss(css: string): string {
+  const decoded = css.includes('\\') || css.includes('/*') ? decodeCss(css) : css;
+  const base = decoded !== css && FETCHING.test(decoded) ? decoded : css;
+  return stripFetches(base).replace(/<\/style/gi, '<\\/style');
+}
+
+/** Static equivalents of the viewer's in-page state restoration, applied to a copy of the attrs. */
+function restoredState(name: string, raw: Record<string, string>): { attrs: Record<string, string>; textarea?: string } {
+  const attrs = { ...raw };
+  let textarea: string | undefined;
+  if (attrs.__playwright_value_ !== undefined) {
+    if (name === 'INPUT' && !/^(checkbox|radio|file)$/i.test(attrs.type || '')) attrs.value = attrs.__playwright_value_;
+    if (name === 'TEXTAREA') textarea = attrs.__playwright_value_;
+  }
+  if (attrs.__playwright_checked_ !== undefined) { if (attrs.__playwright_checked_ === 'true') attrs.checked = ''; else delete attrs.checked; }
+  if (attrs.__playwright_selected_ !== undefined) { if (attrs.__playwright_selected_ === 'true') attrs.selected = ''; else delete attrs.selected; }
+  if (attrs.__playwright_popover_open_ !== undefined) delete attrs.popover;
+  if (name === 'DIALOG' && attrs.__playwright_dialog_open_ !== undefined) attrs.open = '';
+  return { attrs, textarea };
+}
+
+function attrText(name: string, attrs: Record<string, string>): string {
+  const out: string[] = [];
+  for (const [k, v] of Object.entries(attrs)) {
+    const lk = k.toLowerCase();
+    if (lk.startsWith('__playwright_') && lk !== '__playwright_target__') continue;
+    if (lk.startsWith('on') || !/^[A-Za-z_:][-A-Za-z0-9_:.]*$/.test(k)) continue;
+    if (URL_ATTRS.has(lk)) {
+      // A link without href loses its role; keep the attribute, drop the URL.
+      if ((name === 'A' || name === 'AREA') && lk === 'href') out.push(' href="#"');
+      continue;
+    }
+    out.push(' ', k, '="', escapeAttr(lk === 'style' ? sanitizeCss(String(v)) : String(v)), '"');
+  }
+  return out.join('');
+}
+
+export function renderSnapshot(store: SnapshotStore, snapshot: FrameSnapshot, readResource: (sha1: string) => string | null): RenderedSnapshot {
+  const stats: RenderStats = { refs: 0, brokenRefs: 0, stylesheets: 0, stylesheetsMissing: 0 };
+  const out: string[] = [];
+  const sheets: Array<{ snap: FrameSnapshot; href: string; media?: string }> = [];
+  let headSeen = false;
+  const visit = (n: SnapNode, snap: FrameSnapshot, parent: string | undefined): void => {
+    if (isRef(n)) { const d = store.deref(n, snap, stats); if (d) visit(d.n, d.snap, parent); return; }
+    if (typeof n === 'string') { out.push(parent === 'STYLE' ? sanitizeCss(n) : escapeHtml(n)); return; }
+    if (!isEl(n) || !TAG_NAME.test(n[0])) return;
+    const name = n[0].toUpperCase();
+    const raw = attrsOf(n);
+    if (name === 'SCRIPT' || name === 'NOSCRIPT' || name === 'BASE' || (name === 'META' && raw['http-equiv'] !== undefined)) return;
+    if (name === 'LINK') {
+      if ((raw.rel || '').toLowerCase().split(/\s+/).includes('stylesheet') && raw.href) {
+        out.push(`<!--SUNGEN_SHEET_${sheets.length}-->`);
+        sheets.push({ snap, href: raw.href, media: raw.media });
+      }
+      return;
+    }
+    if (name === 'TEMPLATE' && raw.__playwright_style_sheet_ !== undefined) { out.push('<style>', sanitizeCss(raw.__playwright_style_sheet_), '</style>'); return; }
+    if (name === 'TEMPLATE' && raw.__playwright_shadow_root_ !== undefined) {
+      out.push('<template shadowrootmode="open">');
+      kidsOf(n).forEach((k) => visit(k, snap, 'TEMPLATE'));
+      out.push('</template>');
+      return;
+    }
+    const { attrs, textarea } = restoredState(name, raw);
+    // Only THIS call's target keeps the marker, as `__playwright_target__="<callId>"` (v9 writes "").
+    const mark = attrs.__playwright_target__;
+    if (mark !== undefined) {
+      if (mark === snapshot.callId || (mark === '' && snap.callId === snapshot.callId)) attrs.__playwright_target__ = snapshot.callId;
+      else delete attrs.__playwright_target__;
+    }
+    out.push('<', name, attrText(name, attrs), '>');
+    if (name === 'HEAD' && !headSeen) { headSeen = true; out.push(`<meta http-equiv="Content-Security-Policy" content="${REPLAY_CSP}">`); }
+    if (textarea !== undefined) out.push(escapeHtml(textarea));
+    else kidsOf(n).forEach((k) => visit(k, snap, name));
+    if (!AUTO_CLOSING.has(name)) out.push('</', name, '>');
+  };
+  visit(snapshot.html, snapshot, undefined);
+  let html = out.join('');
+  sheets.forEach((s, i) => {
+    const sha1 = store.stylesheetSha1(s.snap, s.href);
+    const css = sha1 ? readResource(sha1) : null;
+    if (css === null) stats.stylesheetsMissing++; else stats.stylesheets++;
+    const media = s.media ? ` media="${escapeAttr(s.media)}"` : '';
+    html = html.replace(`<!--SUNGEN_SHEET_${i}-->`, () => (css === null ? '' : `<style${media}>${sanitizeCss(css)}</style>`));
+  });
+  const csp = headSeen ? '' : `<meta http-equiv="Content-Security-Policy" content="${REPLAY_CSP}">`;
+  const doctype = snapshot.doctype ? `<!DOCTYPE ${escapeHtml(snapshot.doctype)}>` : '';
+  return { html: doctype + csp + html, stats };
+}

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,59 @@
+/**
+ * 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 not older than the .feature files and the lock it is asked to prove —
+ *                 judged by their content, not their file time (#967, trace-freshness.ts)
+ */
+import { createHash } from 'crypto';
+import * as fs from 'fs';
+import * as path from 'path';
+import type { ParsedTrace } from './trace-file-reader';
+import { staleReason, UnitContract } from './trace-freshness';
+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;
+  /** The unit's contract as it is now; null when no contract is proven (derive reads traces to write one). */
+  contract: UnitContract | null;
+}
+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)');
+  }
+  const stale = i.contract ? staleReason(i.contract, i.record) : null;
+  if (stale) return fail(stale);
+  return { ok: true, specFile: attempt.file };
+}