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

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

@@ -0,0 +1,144 @@
+/**
+ * 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 { FileRead, readFileOnce } from './read-file-once';
+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;
+    },
+  };
+}
+
+/**
+ * A trace opened once (read-file-once.ts) → parsed: the size was checked on the descriptor BEFORE it
+ * was read into memory. `missing` / `outside` are the caller's to report; here they throw.
+ */
+export function traceFromRead(read: FileRead, label: string, limits: TraceZipLimits = traceZipLimits()): ParsedTrace {
+  switch (read.status) {
+    case 'read': return readTraceBuffer(read.bytes, read.real, limits);
+    case 'too-large': throw new TraceRejected('zip.too-large', `${read.size} B > ${limits.maxZipBytes}`);
+    case 'not-a-file': throw new TraceRejected('zip.malformed', `${label} is not a regular file`);
+    case 'missing': throw new TraceRejected('zip.malformed', `${label} does not exist`);
+    default: throw new TraceRejected('zip.malformed', `${label} was not read: ${read.why}`);
+  }
+}
+
+/** Read a trace from a trusted path (a fixture, a test): a regular file, opened once. */
+export function readTraceFile(file: string, limits: TraceZipLimits = traceZipLimits()): ParsedTrace {
+  return traceFromRead(readFileOnce(file, limits.maxZipBytes), file, limits);
+}

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

@@ -0,0 +1,68 @@
+/**
+ * A trace → its contract fingerprint: the rendered Gherkin steps normalized by the SAME parser and
+ * normalizer a hand-written `.feature` goes through (DOS-14.1), then hashed with the implementation
+ * path (DOS-14.2). So the fingerprint of a trace and the lock of the `.free.feature` derived from it
+ * are equal by construction — not by a second, parallel normalizer that could drift.
+ *
+ * The rendered steps are written to a throw-away `.feature` and read back with
+ * `scenariosOfFeatureFile`; nothing else in the pipeline parses Gherkin.
+ */
+import * as fs from 'fs';
+import * as os from 'os';
+import * as path from 'path';
+import { contractHash } from '../contract-hash';
+import type { ContractStep, Implementation } from '../contract-schema';
+import { scenariosOfFeatureFile } from '../normalize-feature-steps';
+import type { RenderedStep } from '../render-free-gherkin';
+
+const KEYWORD = /^(Given|When|Then|And|But)\s/;
+
+/** Normalize several step lists in one parse; `lines[i]` are full Gherkin lines (keyword first). */
+export function normalizeGherkinLines(blocks: string[][]): ContractStep[][] {
+  if (!blocks.length) return [];
+  const dir = fs.mkdtempSync(path.join(os.tmpdir(), 'sungen-fingerprint-'));
+  try {
+    const file = path.join(dir, 'fingerprint.feature');
+    const text = ['Feature: fingerprint', '', ...blocks.flatMap((lines, i) => [
+      `  Scenario: FP-${i + 1}0`, ...lines.map((l) => `    ${KEYWORD.test(l.trim()) ? l.trim() : `When ${l.trim()}`}`), '',
+    ])].join('\n');
+    fs.writeFileSync(file, text);
+    const parsed = scenariosOfFeatureFile(file);
+    if (parsed.length !== blocks.length) throw new Error(`fingerprint: ${blocks.length} step lists normalized to ${parsed.length} scenarios`);
+    return parsed.map((s) => s.steps);
+  } finally {
+    fs.rmSync(dir, { recursive: true, force: true });
+  }
+}
+
+export interface TraceFingerprint {
+  steps: ContractStep[];
+  hash: string;
+  rendered: RenderedStep[];
+  /** impl:code: each `test.step` title (normalized) and the indexes of the steps it holds. */
+  groups: Array<{ title: string; titleStep: ContractStep; members: number[] }>;
+}
+
+/** Many fingerprints from ONE temp-file parse (a unit's scenarios × runs) — the guard path's cost. */
+export function fingerprintsOf(items: Array<{ rendered: RenderedStep[]; implementation: Implementation }>): TraceFingerprint[] {
+  const blocks: string[][] = [];
+  const plan = items.map(({ rendered, implementation }) => {
+    const titles = implementation === 'impl:code' ? [...new Set(rendered.map((r) => r.group).filter((g): g is string => !!g))] : [];
+    const at = blocks.push(rendered.map((r) => `${r.keyword} ${r.sentence}`)) - 1;
+    const titlesAt = titles.length ? blocks.push(titles) - 1 : -1;
+    return { at, titlesAt, titles };
+  });
+  const normalized = normalizeGherkinLines(blocks);
+  return items.map(({ rendered, implementation }, i) => {
+    const { at, titlesAt, titles } = plan[i];
+    const steps = normalized[at];
+    const titleSteps = titlesAt >= 0 ? normalized[titlesAt] : [];
+    const groups = titles.map((title, k) => ({
+      title, titleStep: titleSteps[k], members: rendered.map((r, j) => (r.group === title ? j : -1)).filter((j) => j >= 0),
+    }));
+    return { steps, hash: contractHash(implementation, steps), rendered, groups };
+  });
+}
+
+export const fingerprintOf = (rendered: RenderedStep[], implementation: Implementation): TraceFingerprint =>
+  fingerprintsOf([{ rendered, implementation }])[0];

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

@@ -0,0 +1,110 @@
+/**
+ * Is a trace newer than the contract it is asked to prove? (DOS-14.6: a trace older than the
+ * `.feature` or the lock is refused.) Judged by CONTENT, never by file time alone (#967): a `touch`,
+ * a checkout or a fresh clone changes no byte, so it stales nothing; an edit after the run always does.
+ *
+ *   schema 2 record   the reporter hashed every `.feature` and `contracts.lock.yaml` under `qa/` when
+ *                     the run started. Each of the unit's contract files must hash NOW to what the run
+ *                     saw: one that changed since, or did not exist yet, is newer than the trace → stale
+ *   schema 1 record   an older reporter recorded no content, so the files are dated against the run's
+ *                     start (the record's `startedAt`): one last written before it is older than the run;
+ *                     one written after it still is when git holds it unchanged and the commit that last
+ *                     changed it is an ancestor of HEAD committed before the run started (its bytes ARE
+ *                     that commit's). Anything else — edited, uncommitted, untracked, committed after the
+ *                     run started, no git, git failed or slow — is stale: fail closed.
+ *
+ * Limit of the schema-1 path: a commit time is what the committer's clock (or GIT_COMMITTER_DATE) said,
+ * so a backdated commit passes the time check — time-based checks cannot see through that. Schema 2
+ * compares content and retires this path: re-running the free tests once with the current reporter is
+ * the remedy.
+ */
+import { execFileSync } from 'child_process';
+import { createHash } from 'crypto';
+import * as fs from 'fs';
+import * as path from 'path';
+import { lockPathFor } from '../contracts-lock-file';
+import { contractFeatureFiles } from '../normalize-feature-steps';
+import type { RunRecord } from './trace-run-record';
+
+interface ContractFile { rel: string; sha: string; mtimeMs: number }
+interface LastCommit { sha: string; ms: number }
+/** A unit's contract as it is NOW — its `.feature` files and lock, read once per verdict. */
+export interface UnitContract {
+  projectRoot: string;
+  files: ContractFile[];
+  /** Schema 1 only, asked of git at most once: project path → the last commit that changed each file git holds unchanged. */
+  committed?: Map<string, LastCommit> | null;
+  /** Schema 1 only: commit → is it an ancestor of HEAD (asked once per commit). */
+  ancestors?: Map<string, boolean>;
+}
+
+/** Inside the Claude Code guard too: a slow git leaves a schema-1 trace stale rather than the hook waiting. */
+const GIT_TIMEOUT_MS = 2_000;
+const posix = (p: string): string => p.split(path.sep).join('/');
+
+export function unitContract(projectRoot: string, unit: { name: string; dir: string }): UnitContract {
+  const root = path.resolve(projectRoot);
+  const lock = path.resolve(lockPathFor(unit.dir));
+  const files = [...(fs.existsSync(lock) ? [lock] : []), ...contractFeatureFiles(unit.dir, unit.name)].map((abs) => {
+    let sha = 'unreadable';   // never equal to a recorded sha256: an unreadable contract file is stale
+    let mtimeMs = Number.POSITIVE_INFINITY;
+    try { sha = createHash('sha256').update(fs.readFileSync(abs)).digest('hex'); mtimeMs = fs.statSync(abs).mtimeMs; } catch { /* stale */ }
+    return { rel: posix(path.relative(root, abs)), sha, mtimeMs };
+  });
+  return { projectRoot: root, files };
+}
+
+function git(cwd: string, args: string[]): string | null {
+  try { return execFileSync('git', args, { cwd, stdio: ['ignore', 'pipe', 'ignore'], timeout: GIT_TIMEOUT_MS, maxBuffer: 16 * 1024 * 1024 }).toString('utf8'); } catch { return null; }
+}
+
+/**
+ * Each contract file git holds unchanged → the last commit (first-parent history, merges included)
+ * that changed it, with its committer time. Two git calls for the whole unit; null when git cannot say.
+ * Paths are passed as literal pathspecs: no glob or `:(magic)` reading of a unit's file names.
+ */
+function committedTimes(c: UnitContract): Map<string, LastCommit> | null {
+  if (c.committed !== undefined) return c.committed;
+  const rels = c.files.map((f) => f.rel);
+  const changed = git(c.projectRoot, ['--literal-pathspecs', 'diff', '--name-only', '--relative', '-z', 'HEAD', '--', ...rels]);
+  const log = git(c.projectRoot, ['-c', 'core.quotePath=false', '--literal-pathspecs', 'log', '--first-parent', '-m', '-n', '500', '--format=%x01%H %ct', '--name-only', '--relative', '--', ...rels]);
+  if (changed === null || log === null) return (c.committed = null);
+  const dirty = new Set(changed.split('\0').filter(Boolean));
+  const times = new Map<string, LastCommit>();
+  let at: LastCommit | null = null;
+  for (const raw of log.split('\n')) {
+    const line = raw.trim();
+    if (raw.startsWith('\x01')) {
+      const [sha, ct] = raw.slice(1).trim().split(' ');
+      at = /^[0-9a-f]{40,64}$/.test(sha ?? '') && Number(ct) > 0 ? { sha, ms: Number(ct) * 1000 } : null;
+    } else if (line && at && !times.has(line) && !dirty.has(line)) times.set(line, at);
+  }
+  return (c.committed = times);
+}
+
+/** Is `sha` an ancestor of HEAD? First-parent history says so already; asserted, never assumed. */
+function isAncestorOfHead(c: UnitContract, sha: string): boolean {
+  if (!c.ancestors) c.ancestors = new Map();
+  if (!c.ancestors.has(sha)) c.ancestors.set(sha, git(c.projectRoot, ['merge-base', '--is-ancestor', sha, 'HEAD']) !== null);
+  return c.ancestors.get(sha)!;
+}
+
+/** Why a trace bound to `record` is older than the unit's contract — null when it is not. */
+export function staleReason(c: UnitContract, record: RunRecord): string | null {
+  if (record.contract) {
+    const f = c.files.find((x) => record.contract![x.rel] !== x.sha);
+    if (!f) return null;
+    const why = record.contract[f.rel] === undefined ? 'it did not exist when the run started' : 'its content changed after the run';
+    return `the trace is older than ${f.rel}: ${why} (stale) — re-run the test`;
+  }
+  const runStart = Date.parse(record.startedAt);   // unreadable → nothing is "before the run": stale
+  const late = c.files.filter((f) => !(f.mtimeMs <= runStart));
+  if (!late.length) return null;
+  const committed = committedTimes(c);
+  const vouched = (rel: string): boolean => {
+    const last = committed?.get(rel);
+    return !!last && last.ms <= runStart && isAncestorOfHead(c, last.sha);
+  };
+  const f = late.find((x) => !vouched(x.rel));
+  return f ? `the trace is older than ${f.rel}: it was written after the run, and no commit from before the run holds its bytes (stale) — re-run the test` : null;
+}

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

@@ -0,0 +1,77 @@
+/**
+ * Every target of a trace → its identity (DOS-14.5): the driver's answer from the identity cache
+ * when one exists for the exact HTML core rendered, otherwise core's heuristic (always `low`).
+ *
+ * `resolveWithDriver` is the only asynchronous part of trace conformance: it renders the snapshots,
+ * asks the registered `traceIdentity` resolver (driver-ui: a real browser, JS off, every request
+ * blocked) for the ones not cached yet, and writes the cache. Everything else stays a plain
+ * function of the files on disk, so the CLI and the Claude Code guard build the same verdict.
+ */
+import { CachedIdentity, IdentityCache, readIdentityCache, writeIdentityCache } from './identity-cache';
+import { resolveCallTarget, CallTarget } from './snapshot-resolver';
+import { SnapshotStore } from './snapshot-store';
+import { heuristicIdentity, TraceIdentityRequest, TraceIdentityResolver, TRUSTED_RESOLVER, validIdentityResult } from './target-identity';
+import type { ParsedTrace } from './trace-file-reader';
+import { traceIntentSteps, IntentStep } from './trace-steps';
+import type { ResolvedTarget } from '../render-free-gherkin';
+
+const NO_DRIVER = 'no driver identity yet — run `sungen contract check --trace` (needs @sungen/driver-ui and a browser)';
+
+/** Steps aimed at the page itself carry no element identity. */
+export const isPageLevel = (s: IntentStep): boolean =>
+  s.method === 'goto' || /^keyboard/.test(s.method) || /^to\.have\.(url|title)$/.test(String(s.params.expression ?? '')) || s.kind.startsWith('opaque');
+
+function targetCalls(trace: ParsedTrace, steps: IntentStep[]): Array<{ callId: string; target: CallTarget | null }> {
+  const store = new SnapshotStore(trace.library);
+  return steps.filter((s) => s.callId && !isPageLevel(s)).map((s) => ({ callId: s.callId!, target: resolveCallTarget(store, trace, s.callId!) }));
+}
+
+export function identitiesFor(trace: ParsedTrace, steps: IntentStep[], cache: IdentityCache): Map<string, ResolvedTarget> {
+  const out = new Map<string, ResolvedTarget>();
+  for (const { callId, target } of targetCalls(trace, steps)) {
+    if (!target) { out.set(callId, { identity: heuristicIdentity(null, 'no snapshot marks this target') }); continue; }
+    const hit = cache.entries.get(target.snapshotSha256);
+    if (!hit) { out.set(callId, { identity: heuristicIdentity(target.facts, NO_DRIVER), facts: target.facts }); continue; }
+    // What core already knows (missing CSS, broken refs) caps the driver's answer, whatever it says.
+    const reasons = [...target.capReasons, ...hit.reasons];
+    out.set(callId, {
+      identity: { ...hit, identityConfidence: reasons.length ? 'low' : hit.identityConfidence, reasons, source: 'driver' },
+      facts: target.facts,
+    });
+  }
+  return out;
+}
+
+/** One replay request per element target of a trace, keyed by the sha256 of its rendered HTML. */
+export function identityRequestsFor(trace: ParsedTrace): TraceIdentityRequest[] {
+  return targetCalls(trace, traceIntentSteps(trace)).filter((t) => t.target).map(({ callId, target }) => ({
+    key: target!.snapshotSha256, html: target!.html, viewport: target!.viewport,
+    targetSelector: `[__playwright_target__="${callId}"]`, capReasons: target!.capReasons,
+  }));
+}
+
+/** Ask the driver about every not-yet-cached target of these traces; rewrite the cache. */
+/** `keys`: every target of the given traces (cached or asked) — what the caller reports on. */
+export async function resolveWithDriver(projectRoot: string, traces: ParsedTrace[], resolver: TraceIdentityResolver): Promise<{ asked: number; resolver: string; blockedRequests: number; keys: string[] }> {
+  const { cache } = readIdentityCache(projectRoot);
+  // The cache is project-wide (every unit's traces): answers are only ever ADDED, never pruned here.
+  const keep = new Map<string, CachedIdentity>(cache.entries);
+  const all = traces.flatMap(identityRequestsFor);
+  const keys = [...new Set(all.map((req) => req.key))];
+  const requests = new Map<string, TraceIdentityRequest>();
+  for (const req of all) if (!keep.has(req.key)) requests.set(req.key, req);
+  if (!requests.size) return { asked: 0, resolver: cache.resolver, blockedRequests: 0, keys };
+  const answer = await resolver({ requests: [...requests.values()] });
+  if (!answer || !Array.isArray(answer.results)) throw new Error('the trace identity resolver returned no results');
+  if (!TRUSTED_RESOLVER.test(String(answer.resolver)) || typeof answer.browser !== 'string' || !answer.browser) {
+    throw new Error(`the trace identity resolver "${String(answer.resolver).slice(0, 40)}" is not driver-ui's, or named no browser — its answers are not kept`);
+  }
+  for (const raw of answer.results) {
+    const r = validIdentityResult(raw);
+    if (!r || !requests.has(r.key)) throw new Error(`the trace identity resolver returned a malformed or unasked-for result (${JSON.stringify(raw).slice(0, 120)})`);
+    const { key, ...rest } = r;
+    keep.set(key, { ...rest, browser: answer.browser.slice(0, 100) });
+  }
+  writeIdentityCache(projectRoot, answer.resolver, keep);
+  return { asked: requests.size, resolver: String(answer.resolver), blockedRequests: Number(answer.blockedRequests) || 0, keys };
+}

package/src/contract/trace/trace-run-record.ts

@@ -0,0 +1,96 @@
+/**
+ * sungen's own run record (G5, DOS-14.6): written by `@sungen/driver-ui`'s run-record reporter
+ * next to the traces, read here STRICTLY — it is the only place a trace's run id and the hash of
+ * the code that produced it live, so an unknown key, a wrong type or a malformed hash means the
+ * record is not trusted at all (every trace it would vouch for is unbound).
+ *
+ * Found by convention: `<project>/test-results-free/sungen-run-record*.json` — the free-test config's
+ * own outputDir (#941) — or `<project>/test-results/sungen-run-record*.json` (one per run or shard).
+ * Playwright wipes its outputDir at the start of every run, so a record and its traces share a
+ * lifetime; the free run has its own so the compiled suite's next run cannot delete its traces.
+ *
+ * Schema 2 (#967) adds `contract`: the sha256 of every `.feature` and `contracts.lock.yaml` under `qa/`
+ * when the run started — what trace freshness compares by content. Schema 1 (an older reporter) has
+ * none; its traces are dated instead (trace-freshness.ts).
+ */
+import * as fs from 'fs';
+import * as path from 'path';
+
+export interface RunRecordAttempt {
+  testId: string; file: string; title: string; retry: number; status: string;
+  startTime: string; duration: number; trace: { sha256: string } | null;
+}
+export interface RunRecord {
+  file: string;
+  runId: string;
+  startedAt: string;
+  playwrightVersion: string;
+  shard: string | null;
+  report: string | null;
+  specs: Record<string, string>;
+  /** Schema 2: project path → sha256 of each contract file at run start. null: schema 1 (no content recorded). */
+  contract: Record<string, string> | null;
+  attempts: RunRecordAttempt[];
+}
+
+const TOP_V1: ReadonlySet<string> = new Set(['schema', 'tool', 'runId', 'startedAt', 'playwrightVersion', 'shard', 'report', 'specs', 'attempts']);
+const TOP_V2: ReadonlySet<string> = new Set([...TOP_V1, 'contract']);
+const ATTEMPT = new Set(['testId', 'file', 'title', 'retry', 'status', 'startTime', 'duration', 'trace']);
+const SHA = /^[0-9a-f]{64}$/;
+const isObj = (v: unknown): v is Record<string, unknown> => !!v && typeof v === 'object' && !Array.isArray(v);
+
+/** The free / impl:code run's own outputDir (the documented free-test config); compiled runs clear `test-results/`. */
+export const FREE_RUN_DIR = 'test-results-free';
+/** Where run records are read, in this order: the free run's dir, then Playwright's default (older configs). */
+export const RUN_RECORD_DIRS: readonly string[] = [FREE_RUN_DIR, 'test-results'];
+
+export function findRunRecords(projectRoot: string): string[] {
+  return RUN_RECORD_DIRS.flatMap((rel) => {
+    const dir = path.join(projectRoot, rel);
+    let names: string[];
+    try { names = fs.readdirSync(dir); } catch { return []; }
+    return names.filter((n) => /^sungen-run-record(?:\.[A-Za-z0-9._-]+)?\.json$/.test(n)).sort().map((n) => path.join(dir, n));
+  });
+}
+
+function attemptOf(raw: unknown, i: number): RunRecordAttempt {
+  const at = `attempt ${i + 1}`;
+  if (!isObj(raw)) throw new Error(`${at} is not an object`);
+  const extra = Object.keys(raw).find((k) => !ATTEMPT.has(k));
+  if (extra) throw new Error(`${at} has an unknown key "${extra}"`);
+  const { testId, file, title, retry, status, startTime, duration, trace } = raw;
+  if (typeof testId !== 'string' || typeof file !== 'string' || typeof title !== 'string' || typeof status !== 'string') throw new Error(`${at}: testId, file, title and status must be strings`);
+  if (!Number.isInteger(retry) || (retry as number) < 0 || typeof duration !== 'number' || typeof startTime !== 'string' || Number.isNaN(Date.parse(startTime))) {
+    throw new Error(`${at}: retry, duration and startTime are malformed`);
+  }
+  if (trace !== null && !(isObj(trace) && Object.keys(trace).length === 1 && typeof trace.sha256 === 'string' && SHA.test(trace.sha256))) throw new Error(`${at}: trace must be null or {sha256}`);
+  return { testId, file, title, retry: retry as number, status, startTime, duration, trace: trace as RunRecordAttempt['trace'] };
+}
+
+/** Read and check one record (`text`: its bytes, already read once by the caller); throws an Error naming what is wrong. */
+export function readRunRecord(file: string, text?: string): RunRecord {
+  let raw: unknown;
+  try { raw = JSON.parse(text ?? fs.readFileSync(file, 'utf8')); } catch (e) { throw new Error(`not readable JSON (${(e as Error).message.split('\n')[0]})`); }
+  if (!isObj(raw)) throw new Error('not an object');
+  if (raw.tool === 'sungen-trace-run-record' && typeof raw.schema === 'number' && raw.schema > 2) {
+    // A newer driver-ui wrote it (mixed versions): say what to upgrade, not just "not a record".
+    throw new Error(`record schema ${raw.schema} is newer than this sungen — upgrade @sun-asterisk/sungen (core before or together with driver-ui)`);
+  }
+  const keys = raw.schema === 2 ? TOP_V2 : raw.schema === 1 ? TOP_V1 : null;
+  if (!keys || raw.tool !== 'sungen-trace-run-record') throw new Error('not a sungen run record (schema 1 or 2)');
+  const extra = Object.keys(raw).find((k) => !keys.has(k));
+  if (extra) throw new Error(`unknown key "${extra}"`);
+  if (typeof raw.runId !== 'string' || !raw.runId || typeof raw.startedAt !== 'string' || typeof raw.playwrightVersion !== 'string') throw new Error('runId, startedAt and playwrightVersion must be strings');
+  if (raw.shard !== null && typeof raw.shard !== 'string') throw new Error('shard must be a string or null');
+  if (raw.report !== null && typeof raw.report !== 'string') throw new Error('report must be a string or null');
+  if (!isObj(raw.specs) || !Object.values(raw.specs).every((v) => typeof v === 'string' && (v === '' || SHA.test(v)))) throw new Error('specs must map files to sha256');
+  if (raw.schema === 2 && !(isObj(raw.contract) && Object.values(raw.contract).every((v) => typeof v === 'string' && SHA.test(v)))) {
+    throw new Error('contract must map contract files to sha256 (schema 2)');
+  }
+  if (!Array.isArray(raw.attempts)) throw new Error('attempts must be a list');
+  return {
+    file, runId: raw.runId, startedAt: raw.startedAt, playwrightVersion: raw.playwrightVersion, shard: raw.shard as string | null,
+    report: raw.report as string | null, specs: raw.specs as Record<string, string>,
+    contract: raw.schema === 2 ? raw.contract as Record<string, string> : null, attempts: raw.attempts.map(attemptOf),
+  };
+}

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

@@ -0,0 +1,88 @@
+/**
+ * A trace → the test's INTENT, in order (phase 08 requirement 1). What is kept:
+ *
+ *   action         Frame goto / click / dblclick / fill / check / uncheck / selectOption / press /
+ *                  hover / setInputFiles / type / tap, and page keyboard presses
+ *   assert         Frame.expect — a check on an element or the page (url, title)
+ *   opaque-assert  a runner `expect` with no browser call behind it: `expect(await res.json())…`,
+ *                  a check on a JS value — cannot be compared, always review (DOS-14.6)
+ *   opaque-action  an API request, an `evaluate` (canvas…) — behaviour the contract cannot see into
+ *
+ * Dropped as implementation detail: waits (`waitForTimeout`, `waitFor*`), reads (`textContent`,
+ * `isVisible`…), context/page plumbing, and everything in fixtures, runner hooks and teardown —
+ * only the body and user `beforeEach` hooks are the test's behaviour. A focus click right before a
+ * fill on the same element is dropped later, once identities say "same element" (render step).
+ */
+import { classifyStep, isBehaviour, joinCalls, RunnerStep } from './test-step-join';
+import type { ParsedTrace, StackFrame } from './trace-file-reader';
+
+export type IntentKind = 'action' | 'assert' | 'opaque-action' | 'opaque-assert';
+export interface IntentStep {
+  kind: IntentKind;
+  method: string;
+  callId?: string;
+  params: Record<string, unknown>;
+  /** Enclosing `test.step` titles, outermost first (impl:code compares by the first). */
+  group: string[];
+  location?: { file: string; line: number };
+  /** The runner's own words for an opaque step (`Expect "toMatchObject"`, `GET /api/health`). */
+  verbatim?: string;
+  startTime: number;
+}
+
+const FRAME_ACTIONS = new Set(['goto', 'click', 'dblclick', 'fill', 'check', 'uncheck', 'selectOption', 'press', 'hover', 'setInputFiles', 'type', 'tap']);
+const PAGE_KEYS = new Set(['keyboardPress', 'keyboardType', 'keyboardInsertText']);
+const EVALUATE = /^evaluate/;
+
+/** The first frame in the test's own code (not a library, not the runner's `project#` marker). */
+function firstFrame(frames: StackFrame[] | undefined): { file: string; line: number } | undefined {
+  const f = frames?.find((x) => x.file && !x.file.includes('node_modules') && !x.file.endsWith('#'));
+  return f ? { file: f.file, line: f.line } : undefined;
+}
+
+function groupOf(steps: Map<string, RunnerStep>, stepId: string | undefined): string[] {
+  if (!stepId) return [];
+  const w = classifyStep(steps, stepId);
+  return w.phase === 'body' ? w.stepPath : [];
+}
+
+export function traceIntentSteps(trace: ParsedTrace): IntentStep[] {
+  const { steps, calls } = joinCalls(trace);
+  const stacks = new Map(trace.library.map((l) => [l.name, l.stacks]));
+  const out: IntentStep[] = [];
+  const withCall = new Set(calls.map((c) => c.stepId).filter((s): s is string => !!s));
+
+  for (const c of calls) {
+    if (!isBehaviour(c.where)) continue;
+    let kind: IntentKind | null = null;
+    let verbatim: string | undefined;
+    if (c.class === 'Frame' && FRAME_ACTIONS.has(c.method)) kind = 'action';
+    else if (c.class === 'Frame' && c.method === 'expect') kind = 'assert';
+    else if (c.class === 'Page' && PAGE_KEYS.has(c.method)) kind = 'action';
+    else if (c.class === 'APIRequestContext' && c.method === 'fetch') {
+      kind = 'opaque-action';
+      verbatim = `${String(c.params.method ?? 'GET')} ${String(c.params.url ?? '')}`;
+    } else if (EVALUATE.test(c.method) && /^(Frame|Page|JSHandle|ElementHandle|Worker)$/.test(c.class)) {
+      kind = 'opaque-action';
+      verbatim = `${c.class}.${c.method}`;
+    }
+    if (!kind) continue;
+    const runner = c.stepId ? steps.get(c.stepId) : undefined;
+    out.push({
+      kind, method: c.method, callId: c.callId, params: c.params, group: groupOf(steps, c.stepId),
+      location: firstFrame(runner?.stack) ?? firstFrame(stacks.get(c.part)?.get(c.callId)),
+      ...(verbatim ? { verbatim } : {}), startTime: c.startTime,
+    });
+  }
+
+  // A runner `expect` that drove no browser call checked a plain JS value: opaque.
+  const runnerStart = new Map(trace.runner.filter((e) => e.type === 'before').map((e) => [String(e.callId), Number(e.startTime) || 0]));
+  for (const s of steps.values()) {
+    if (s.method !== 'expect' || withCall.has(s.id) || !isBehaviour(classifyStep(steps, s.id))) continue;
+    out.push({
+      kind: 'opaque-assert', method: 'expect', params: s.params, group: groupOf(steps, s.id),
+      location: firstFrame(s.stack), verbatim: s.title, startTime: runnerStart.get(s.id) ?? 0,
+    });
+  }
+  return out.sort((a, b) => a.startTime - b.startTime);
+}