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

package/src/contract/trace/collect-trace-evidence.ts

@@ -8,13 +8,21 @@
  *   refused        the trace exists but may not speak (swapped, stale, rejected zip…)
  *   unsupported    the trace's format version is unknown                       (exit ≠ 0)
  *
+ * Two recorded TESTS claiming one scenario id (#962) make its evidence ambiguous: neither speaks —
+ * `unproven`, both named (scenario-id-claims.ts) — instead of judging two tests' runs as one.
+ *
  * Only traces of the scenario ids asked for are opened, so a unit pays for its own tests only.
  */
 import * as fs from 'fs';
 import * as path from 'path';
+import { isIdLike } from '../../harness/parse';
+import { clip, CONTROL_CHARS } from '../render-free-gherkin';
+import { FileRead, readInsideProject } from './read-file-once';
+import { idsClaimedByTwoTests, twoTestsClaim } from './scenario-id-claims';
 import { bindTrace } from './trace-binding';
-import { readTraceFile, ParsedTrace } from './trace-file-reader';
-import { TraceRejected } from './trace-zip-limits';
+import type { UnitContract } from './trace-freshness';
+import { traceFromRead, ParsedTrace } from './trace-file-reader';
+import { traceZipLimits, TraceRejected } from './trace-zip-limits';
 import { finalAttempt, readPlaywrightReport, ReportResult, ReportTest, scenarioIdOfTest } from './select-final-attempt';
 import { findRunRecords, readRunRecord, RunRecord } from './trace-run-record';
 
@@ -32,78 +40,139 @@ export interface TraceRun {
 }
 export interface ScenarioEvidence { runs: Map<string, TraceRun[]>; problems: string[]; inputs: string[] }
 
+/** A run record or JSON report larger than this is refused before a byte is read (fail closed, #926). */
+export const MAX_EVIDENCE_JSON_BYTES = 64 * 1024 * 1024;
+
+/** Why an evidence file was not read — `outside the project` covers a link out, a swap and a non-file. */
+function notRead(name: string, r: Exclude<FileRead, { status: 'read' }>): string {
+  if (r.status === 'too-large') return `${name} is larger than ${MAX_EVIDENCE_JSON_BYTES / 1024 / 1024} MiB — not read`;
+  if (r.status === 'missing') return `${name} is missing — not read`;
+  return `${name} is outside the project (a symlink?) or not a regular file — not read`;
+}
+
 /** The reason a run is not judged once the verdict's deadline has passed (fail closed). */
 export const OVER_BUDGET = 'verdict budget exceeded; run `sungen contract check`';
-const NO_RECORD = "no sungen run record under test-results/ — run the free tests with trace: 'on' and the sungen run-record reporter";
+const NO_RECORD = "no sungen run record under test-results-free/ (or test-results/) — run the free tests with their own config: outputDir 'test-results-free', trace: 'on' and the sungen run-record reporter";
 
-/** The real path of `file` when it is a regular file INSIDE the project (symlinks resolved); else null. */
-export function insideProject(projectRoot: string, file: string): string | null {
-  try {
-    const root = fs.realpathSync(projectRoot);
-    const real = fs.realpathSync(file);
-    return real.startsWith(root + path.sep) && fs.statSync(real).isFile() ? real : null;
-  } catch { return null; }
+/** `p` relative to `root` when it lies under it, else null. */
+function under(root: string, p: string): string | null {
+  const rel = path.relative(root, p);
+  return rel && !rel.startsWith('..') && !path.isAbsolute(rel) ? rel : null;
 }
 
-function resolveAttachment(projectRoot: string, report: string, p: string): { file?: string; outside?: boolean } {
-  for (const cand of path.isAbsolute(p) ? [p] : [path.resolve(projectRoot, p), path.resolve(path.dirname(report), p)]) {
-    if (!fs.existsSync(cand)) continue;
-    const real = insideProject(projectRoot, cand);
-    return real ? { file: real } : { outside: true };
-  }
-  return {};
+/**
+ * Where a report's trace attachment is: the first candidate that exists (read later, opened once, and
+ * only from inside the project). Playwright writes attachment paths ABSOLUTE, in the checkout that ran;
+ * after a clone or a move that checkout is elsewhere, so a path under the report's own config dir is
+ * first tried at the same place under this project (#967) — the run record's sha256 still binds the bytes.
+ */
+function attachmentPath(projectRoot: string, test: ReportTest, p: string): string | null {
+  const moved = path.isAbsolute(p) && test.configRoot && !under(path.resolve(projectRoot), p) ? under(test.configRoot, p) : null;
+  const candidates = path.isAbsolute(p)
+    ? [...(moved ? [path.resolve(projectRoot, moved)] : []), p]
+    : [path.resolve(projectRoot, p), path.resolve(path.dirname(test.report), p)];
+  return candidates.find((c) => fs.existsSync(c)) ?? null;
 }
 
-function judge(projectRoot: string, record: RunRecord, test: ReportTest, notBefore: number): TraceRun {
+function judge(projectRoot: string, record: RunRecord, test: ReportTest, contract: UnitContract | null): TraceRun {
   const scenarioId = scenarioIdOfTest(test.title, test.tags);
   const base = { scenarioId, test, record };
   const fin = finalAttempt(test);
   if (fin.admissibility !== 'admissible') return { ...base, result: fin.result, status: fin.admissibility, reason: fin.reason };
-  const { file, outside } = resolveAttachment(projectRoot, test.report, fin.result!.tracePath!);
-  if (outside) return { ...base, result: fin.result, status: 'unproven', reason: `the trace ${path.basename(fin.result!.tracePath!)} is outside the project (or not a file) — not read` };
-  if (!file) return { ...base, result: fin.result, status: 'unproven', reason: `no trace at ${fin.result!.tracePath} (the report points at a missing file)` };
+  const missing: TraceRun = { ...base, result: fin.result, status: 'unproven', reason: `no trace at ${fin.result!.tracePath} (the report points at a missing file)` };
+  const cand = attachmentPath(projectRoot, test, fin.result!.tracePath!);
+  if (!cand) return missing;
+  // Opened once, inside the project, and what was opened is what is parsed and hashed (#926).
+  const limits = traceZipLimits();
+  const read = readInsideProject(projectRoot, cand, limits.maxZipBytes);
+  if (read.status === 'missing') return missing;
+  if (read.status === 'outside' || read.status === 'not-a-file') {
+    return { ...base, result: fin.result, status: 'unproven', reason: `the trace ${path.basename(fin.result!.tracePath!)} is outside the project (or not a file) — not read` };
+  }
   let trace: ParsedTrace;
-  try { trace = readTraceFile(file); } catch (e) {
+  try { trace = traceFromRead(read, cand, limits); } catch (e) {
     const unsupported = e instanceof TraceRejected && e.code === 'trace.version-unsupported';
     return { ...base, result: fin.result, status: unsupported ? 'unsupported' : 'refused', reason: `trace refused: ${(e as Error).message}` };
   }
-  const bound = bindTrace({ projectRoot, test, result: fin.result!, record, trace, notBefore });
+  const bound = bindTrace({ projectRoot, test, result: fin.result!, record, trace, contract });
   if (bound.ok === false) return { ...base, result: fin.result, trace, status: 'refused', reason: `trace refused: ${bound.reason}` };
   return { ...base, result: fin.result, trace, status: 'admissible', specFile: bound.specFile };
 }
 
-/** Every judged run of the tests `want` accepts (derive: a unit's tests; check: by scenario id). */
+/**
+ * Every judged run of the tests `want` accepts (derive: a unit's tests; check: by scenario id). A trace
+ * older than `contract` — the unit's .feature files and lock, by content (#967) — is refused; derive,
+ * which writes the contract from the traces, passes null.
+ */
 export function collectRuns(
-  projectRoot: string, want: (id: string, test: ReportTest) => boolean, notBefore: number, deadline = Number.POSITIVE_INFINITY,
-): { runs: TraceRun[]; problems: string[]; inputs: string[]; records: number } {
+  projectRoot: string, want: (id: string, test: ReportTest) => boolean, contract: UnitContract | null, deadline = Number.POSITIVE_INFINITY,
+): { runs: TraceRun[]; problems: string[]; untrusted: string[]; inputs: string[]; records: number; seen: Array<{ id: string; title: string }> } {
   const runs: TraceRun[] = [];
   const problems: string[] = [];
+  const untrusted: string[] = [];
   const inputs: string[] = [];
+  const seen: Array<{ id: string; title: string }> = [];
   const records = findRunRecords(projectRoot);
   for (const file of records) {
     let record: RunRecord;
-    if (!insideProject(projectRoot, file)) { problems.push(`${path.basename(file)} is outside the project (a symlink?) — not read`); continue; }
-    try { record = readRunRecord(file); } catch (e) { problems.push(`${path.basename(file)} is not trusted: ${(e as Error).message}`); continue; }
+    const recordRead = readInsideProject(projectRoot, file, MAX_EVIDENCE_JSON_BYTES);
+    if (recordRead.status !== 'read') { problems.push(notRead(path.basename(file), recordRead)); continue; }
+    try { record = readRunRecord(file, recordRead.bytes.toString('utf8')); } catch (e) {
+      untrusted.push(`${path.basename(file)} is not trusted: ${(e as Error).message}`);
+      problems.push(untrusted[untrusted.length - 1]);
+      continue;
+    }
     if (!record.report) { problems.push(`${path.basename(file)} names no JSON report — add the json reporter to the free-test config`); continue; }
-    const reportFile = insideProject(projectRoot, path.resolve(projectRoot, record.report));
-    if (!reportFile) { problems.push(`${path.basename(file)}: the report ${path.basename(record.report)} is missing or outside the project — not read`); continue; }
+    const reportRead = readInsideProject(projectRoot, path.resolve(projectRoot, record.report), MAX_EVIDENCE_JSON_BYTES);
+    if (reportRead.status !== 'read') { problems.push(`${path.basename(file)}: ${notRead(`the report ${path.basename(record.report)}`, reportRead)}`); continue; }
     let tests: ReportTest[];
-    try { tests = readPlaywrightReport(reportFile); } catch (e) { problems.push((e as Error).message); continue; }
+    try { tests = readPlaywrightReport(reportRead.real, reportRead.bytes.toString('utf8')); } catch (e) { problems.push((e as Error).message); continue; }
     inputs.push(`${record.runId}:${record.report}`);
     for (const test of tests) {
       const id = scenarioIdOfTest(test.title, test.tags);
+      seen.push({ id, title: test.title });
       if (!want(id, test)) continue;
-      runs.push(Date.now() > deadline ? { scenarioId: id, test, record, status: 'unproven', reason: OVER_BUDGET } : judge(projectRoot, record, test, notBefore));
+      runs.push(Date.now() > deadline ? { scenarioId: id, test, record, status: 'unproven', reason: OVER_BUDGET } : judge(projectRoot, record, test, contract));
     }
   }
-  return { runs, problems, inputs, records: records.length };
+  return { runs, problems, untrusted, inputs, records: records.length, seen };
+}
+
+/** A title without its leading id, for comparing words only: `VP-X-001 Login works` → `login works`. */
+const wordsOf = (title: string): string => {
+  const lead = title.match(/^\s*([A-Za-z][A-Za-z0-9.-]*)/)?.[1];
+  return (lead && isIdLike(lead) ? title.trim().slice(lead.length) : title).replace(CONTROL_CHARS, '').replace(/\s+/g, ' ').trim().toLowerCase();
+};
+
+/**
+ * Why no recorded test speaks for `id` (#943): a recorded test with this scenario's title under
+ * ANOTHER id is the usual cause — the id was renamed in the .free.feature (or in the test) and the
+ * other side was not — so that mismatch is named, with the fix.
+ */
+function noTestFor(id: string, name: string | undefined, seen: Array<{ id: string; title: string }>): string {
+  const words = name ? wordsOf(name) : '';
+  const twin = words ? seen.find((t) => t.id !== id && wordsOf(t.title) === words) : undefined;
+  if (!twin) return `no test for ${id} in the recorded run(s)`;
+  // The title and its id come from the report — untrusted: clipped, control characters dropped.
+  const [title, other] = [clip(twin.title), clip(twin.id, 60)];
+  return `no test for ${id} in the recorded run(s) — the recorded test "${title}" (id ${other}) has this scenario's title, so the scenario id and the test no longer match: `
+    + `give the test the id ${id} (in its title and its @tag), or the scenario the id ${other}, then run it again with trace on`;
 }
 
-export function collectScenarioEvidence(projectRoot: string, ids: ReadonlySet<string>, notBefore: number, deadline?: number): ScenarioEvidence {
-  const found = collectRuns(projectRoot, (id) => ids.has(id), notBefore, deadline);
+/** The runs of each scenario id; `names` (id → scenario name) lets a missing test be explained. */
+export function collectScenarioEvidence(
+  projectRoot: string, ids: ReadonlySet<string>, contract: UnitContract | null, deadline?: number, names?: ReadonlyMap<string, string>,
+): ScenarioEvidence {
+  const found = collectRuns(projectRoot, (id) => ids.has(id), contract, deadline);
   const runs = new Map<string, TraceRun[]>([...ids].map((id) => [id, found.runs.filter((r) => r.scenarioId === id)]));
+  // Ambiguous evidence: no run of either test may speak for the id — never one picked arbitrarily.
+  for (const [id, claim] of idsClaimedByTwoTests(projectRoot, found.runs)) {
+    if (runs.has(id)) runs.set(id, [{ scenarioId: id, status: 'unproven', reason: twoTestsClaim(id, claim) }]);
+  }
   for (const [id, list] of runs) {
-    if (!list.length) list.push({ scenarioId: id, status: 'unproven', reason: found.records ? `no test for ${id} in the recorded run(s)` : NO_RECORD });
+    // A record that was not trusted may be why (a newer reporter, a hand edit): the finding says so.
+    const why = found.untrusted.length ? ` — ${found.untrusted.join('; ')}` : '';
+    if (!list.length) list.push({ scenarioId: id, status: 'unproven', reason: found.records ? `${noTestFor(id, names?.get(id), found.seen)}${why}` : NO_RECORD });
   }
   return { runs, problems: found.problems, inputs: found.inputs };
 }

package/src/contract/trace/read-file-once.ts

@@ -0,0 +1,95 @@
+/**
+ * Read trace evidence (a run record, a JSON report, a trace.zip) by opening it ONCE and checking what
+ * was opened (#926) — never "check the path, then read the path", which leaves a window in which the
+ * file can be swapped for a link to anything outside the project.
+ *
+ *   readFileOnce(file)                     a regular file, read from its descriptor; O_NONBLOCK so a
+ *                                          FIFO swapped in cannot hang the guard; size checked on the
+ *                                          descriptor before a byte is read
+ *   readInsideProject(root, file)          the same for a path from untrusted input:
+ *                                            1. its real path must sit inside the project's real root
+ *                                            2. that real path is opened with O_NOFOLLOW (a link put
+ *                                               there in the meantime fails the open)
+ *                                            3. AFTER the open the path is resolved again: still inside,
+ *                                               and the same file (device + inode) as the descriptor —
+ *                                               a swap made before the open and undone after it is caught
+ *
+ * A file truncated or grown while it is read gives the bytes the descriptor had; the caller hashes
+ * those bytes, so nothing unread is ever vouched for.
+ *
+ * Windows has no O_NOFOLLOW (the constant is 0 there): the open follows a link swapped in, and the
+ * device + inode re-check after the open is what refuses it.
+ */
+import * as fs from 'fs';
+import * as path from 'path';
+
+export type FileRead =
+  | { status: 'read'; real: string; bytes: Buffer }
+  | { status: 'missing' }
+  | { status: 'outside'; why: string }
+  | { status: 'not-a-file' }
+  | { status: 'too-large'; size: number };
+
+const { O_RDONLY } = fs.constants;
+const O_NOFOLLOW = fs.constants.O_NOFOLLOW ?? 0;
+const O_NONBLOCK = fs.constants.O_NONBLOCK ?? 0;
+
+function readFd(fd: number, size: number): Buffer {
+  const buf = Buffer.alloc(size);
+  let off = 0;
+  while (off < size) {
+    const n = fs.readSync(fd, buf, off, size - off, off);
+    if (n === 0) break;
+    off += n;
+  }
+  return off === size ? buf : buf.subarray(0, off);
+}
+
+function openAndRead(file: string, flags: number, maxBytes: number, recheck?: (opened: fs.Stats) => string | null): FileRead {
+  let fd: number;
+  try { fd = fs.openSync(file, flags); } catch (e) {
+    const code = (e as NodeJS.ErrnoException).code;
+    if (code === 'ENOENT') return { status: 'missing' };
+    // O_NOFOLLOW on a link: ELOOP (Linux, macOS) or EMLINK (FreeBSD).
+    if (code === 'ELOOP' || code === 'EMLINK') return { status: 'outside', why: 'it became a link while it was opened' };
+    throw e;
+  }
+  try {
+    const st = fs.fstatSync(fd);
+    if (!st.isFile()) return { status: 'not-a-file' };
+    if (st.size > maxBytes) return { status: 'too-large', size: st.size };
+    const moved = recheck?.(st);
+    if (moved) return { status: 'outside', why: moved };
+    return { status: 'read', real: file, bytes: readFd(fd, st.size) };
+  } finally {
+    fs.closeSync(fd);
+  }
+}
+
+/** A regular file, opened once and read from that descriptor. */
+export const readFileOnce = (file: string, maxBytes = Number.POSITIVE_INFINITY): FileRead =>
+  openAndRead(file, O_RDONLY | O_NONBLOCK, maxBytes);
+
+/** A regular file INSIDE the project (symlinks resolved), opened once; see the header for the checks. */
+export function readInsideProject(projectRoot: string, file: string, maxBytes = Number.POSITIVE_INFINITY): FileRead {
+  let root: string;
+  let real: string;
+  try {
+    root = fs.realpathSync(projectRoot);
+    real = fs.realpathSync(file);
+  } catch (e) {
+    return (e as NodeJS.ErrnoException).code === 'ENOENT' ? { status: 'missing' } : { status: 'outside', why: 'its real path cannot be resolved' };
+  }
+  const within = (p: string): boolean => p.startsWith(root + path.sep);
+  if (!within(real)) return { status: 'outside', why: 'its real path is outside the project' };
+  return openAndRead(real, O_RDONLY | O_NOFOLLOW | O_NONBLOCK, maxBytes, (opened) => {
+    try {
+      const again = fs.realpathSync(file);
+      if (!within(again)) return 'it was swapped for a link outside the project while it was opened';
+      const now = fs.statSync(again);
+      return now.dev === opened.dev && now.ino === opened.ino ? null : 'it was swapped for another file while it was opened';
+    } catch {
+      return 'it moved while it was opened';
+    }
+  });
+}

package/src/contract/trace/scenario-id-claims.ts

@@ -0,0 +1,60 @@
+/**
+ * One scenario id, one test (#962): which ids more than one recorded TEST claims, said the same way
+ * by `contract derive` (it refuses) and `contract check` (the id is unproven). One test recorded
+ * again — another run or shard, a retry, a second Playwright project — is still one test: the same
+ * file and the same Playwright test id.
+ *
+ * Each claiming test names the run record(s) it came from. A test that only an older run's record
+ * under `test-results/` still mentions — while another claim comes from the free config's own
+ * `test-results-free/` — is most likely gone: that record is offered for deletion.
+ */
+import * as path from 'path';
+import { clip } from '../render-free-gherkin';
+import type { TraceRun } from './collect-trace-evidence';
+import { FREE_RUN_DIR } from './trace-run-record';
+
+export interface IdClaim {
+  /** `file:line "title" (run record <path>)` per claiming test, sorted. */
+  tests: string[];
+  /** Project-relative records under test-results/ that are a claim's only source, next to a test-results-free/ claim. */
+  staleRecords: string[];
+}
+
+const posix = (p: string): string => p.split(path.sep).join('/');
+/** A run's project-relative test file: the run record's (what the binding checks), else the report's. */
+const testFileOf = (r: TraceRun): string => r.record?.attempts.find((a) => a.testId === r.test?.testId)?.file ?? r.test?.file ?? '?';
+const label = (r: TraceRun, records: string[]): string =>
+  `${clip(testFileOf(r), 200)}:${r.test?.line ?? 0} "${clip(r.test?.title ?? '')}" (run record ${records.map((f) => clip(f, 200)).join(', ')})`;
+
+export function idsClaimedByTwoTests(projectRoot: string, runs: readonly TraceRun[]): Map<string, IdClaim> {
+  const byId = new Map<string, Map<string, { run: TraceRun; records: Set<string> }>>();
+  for (const r of runs) {
+    if (!r.test) continue;
+    const tests = byId.get(r.scenarioId) ?? new Map<string, { run: TraceRun; records: Set<string> }>();
+    const key = `${testFileOf(r)}\0${r.test.testId}`;
+    const entry = tests.get(key) ?? { run: r, records: new Set<string>() };
+    if (r.record?.file) entry.records.add(posix(path.relative(projectRoot, r.record.file)));
+    tests.set(key, entry);
+    byId.set(r.scenarioId, tests);
+  }
+  const claims = new Map<string, IdClaim>();
+  for (const [id, tests] of byId) {
+    if (tests.size < 2) continue;
+    const entries = [...tests.values()].map((t) => ({ ...t, records: [...t.records].sort() }));
+    const inFreeDir = entries.some((t) => t.records.some((f) => f.startsWith(`${FREE_RUN_DIR}/`)));
+    const legacyOnly = entries.filter((t) => t.records.length > 0 && t.records.every((f) => f.startsWith('test-results/')));
+    claims.set(id, {
+      tests: entries.map((t) => label(t.run, t.records)).sort(),
+      staleRecords: inFreeDir ? [...new Set(legacyOnly.flatMap((t) => t.records))].sort() : [],
+    });
+  }
+  return claims;
+}
+
+/** What to tell the user when several tests claim one id — check and derive say it the same way. */
+export function twoTestsClaim(id: string, claim: IdClaim): string {
+  const stale = claim.staleRecords.length
+    ? `; if that test is gone, delete ${claim.staleRecords.join(', ')} — an older run's record (free tests now record under ${FREE_RUN_DIR}/)`
+    : '';
+  return `${claim.tests.length} recorded tests claim ${id}: ${claim.tests.join(', ')} — give each test its own ID (its title's leading ID, or its @tag), then run them again with trace on${stale}`;
+}

package/src/contract/trace/select-final-attempt.ts

@@ -11,10 +11,15 @@
  * leading id, else the whole title — the same rule the contract uses for a scenario name.
  */
 import * as fs from 'fs';
+import * as path from 'path';
 import { isIdLike } from '../../harness/parse';
 
 export interface ReportResult { retry: number; status: string; startTime: string; duration: number; tracePath: string | null }
-export interface ReportTest { testId: string; title: string; file: string; line: number; tags: string[]; project: string; results: ReportResult[]; report: string }
+export interface ReportTest {
+  testId: string; title: string; file: string; line: number; tags: string[]; project: string; results: ReportResult[]; report: string;
+  /** The directory of the config that ran (`config.configFile`, absolute as Playwright writes it) — where absolute attachment paths start. */
+  configRoot?: string;
+}
 export type Admissibility = 'admissible' | 'inconclusive' | 'unproven';
 
 const isObj = (v: unknown): v is Record<string, unknown> => !!v && typeof v === 'object' && !Array.isArray(v);
@@ -32,12 +37,14 @@ function resultOf(r: unknown): ReportResult | null {
   return { retry: r.retry as number, status: r.status, startTime: String(r.startTime ?? ''), duration: Number(r.duration) || 0, tracePath: trace?.path ?? null };
 }
 
-/** Every test of a report; throws when the file is not a Playwright JSON report at all. */
-export function readPlaywrightReport(file: string): ReportTest[] {
+/** Every test of a report (`text`: its bytes, already read once by the caller); throws when it is not a Playwright JSON report at all. */
+export function readPlaywrightReport(file: string, text?: string): ReportTest[] {
   let doc: unknown;
-  try { doc = JSON.parse(fs.readFileSync(file, 'utf8')); } catch (e) { throw new Error(`the JSON report ${file} is not readable (${(e as Error).message.split('\n')[0]})`); }
+  try { doc = JSON.parse(text ?? fs.readFileSync(file, 'utf8')); } catch (e) { throw new Error(`the JSON report ${file} is not readable (${(e as Error).message.split('\n')[0]})`); }
   if (!isObj(doc) || !Array.isArray(doc.suites)) throw new Error(`${file} is not a Playwright JSON report (no suites)`);
   const out: ReportTest[] = [];
+  const configFile = isObj(doc.config) && typeof doc.config.configFile === 'string' && path.isAbsolute(doc.config.configFile) ? doc.config.configFile : null;
+  const configRoot = configFile ? { configRoot: path.dirname(configFile) } : {};
   for (const top of doc.suites) {
     for (const spec of specsOf(top)) {
       if (typeof spec.id !== 'string' || typeof spec.title !== 'string' || typeof spec.file !== 'string') continue;
@@ -46,7 +53,7 @@ export function readPlaywrightReport(file: string): ReportTest[] {
         const results = arr(t.results).map(resultOf).filter((r): r is ReportResult => !!r).sort((a, b) => a.retry - b.retry);
         out.push({
           testId: spec.id, title: spec.title, file: spec.file, line: Number(spec.line) || 0,
-          tags: arr(spec.tags).map(String), project: String(t.projectName ?? ''), results, report: file,
+          tags: arr(spec.tags).map(String), project: String(t.projectName ?? ''), results, report: file, ...configRoot,
         });
       }
     }

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

@@ -1,7 +1,8 @@
 /**
  * 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. A library call's `stepId` is the runner step's
- * `callId`; walking the runner's `parentId` chain says where the call ran:
+ * 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)
@@ -26,7 +27,7 @@ export type CallPhase =
   | { phase: 'unjoined' };
 
 export interface JoinedCall {
-  part: string; callId: string; callNumber: number; class: string; method: string;
+  part: string; callId: string; class: string; method: string;
   params: Record<string, unknown>; stepId?: string; where: CallPhase; failed: boolean; startTime: number;
 }
 
@@ -90,9 +91,9 @@ export function joinCalls(trace: ParsedTrace): { steps: Map<string, RunnerStep>;
     for (const e of part.events) {
       if (e.type !== 'before') continue;
       const callId = str(e.callId);
-      const stepId = str(e.stepId) || undefined;
+      const stepId = str(e.stepId) || (part.version >= 10 ? callId : '') || undefined;
       calls.push({
-        part: part.name, callId, callNumber: Number(callId.replace(/^call@/, '')) || 0, class: str(e.class), method: str(e.method),
+        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,
       });

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

@@ -8,12 +8,14 @@
  *   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
+ *   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';
 
@@ -23,8 +25,8 @@ export interface BindingInput {
   result: ReportResult;
   record: RunRecord;
   trace: ParsedTrace;
-  /** Epoch ms: the newest mtime of the unit's .feature files and lock. */
-  notBefore: number;
+  /** 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 };
 
@@ -51,6 +53,7 @@ export function bindTrace(i: BindingInput): Binding {
   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');
+  const stale = i.contract ? staleReason(i.contract, i.record) : null;
+  if (stale) return fail(stale);
   return { ok: true, specFile: attempt.file };
 }

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

@@ -5,20 +5,25 @@
  *   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 number → source frames (`file:line` of an opaque step)
+ *   <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 { 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 }
-export interface LibraryPart { name: string; events: TraceEvent[]; network: TraceEvent[]; stacks: Map<number, StackFrame[]> }
+/**
+ * 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;
@@ -56,19 +61,21 @@ function parseJsonl(zip: ZipArchive, name: string): TraceEvent[] {
   return out;
 }
 
-function parseStacks(zip: ZipArchive, name: string): Map<number, StackFrame[]> {
-  const out = new Map<number, StackFrame[]>();
+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) || typeof row[0] !== 'number' || !Array.isArray(row[1])) continue;
+    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(row[0], frames);
+    out.set(id, frames);
   }
   return out;
 }
@@ -81,9 +88,12 @@ export function readTraceBuffer(buf: Buffer, label: string, limits: TraceZipLimi
   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,
-      events: parseJsonl(zip, 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`),
     };
@@ -114,10 +124,21 @@ export function readTraceBuffer(buf: Buffer, label: string, limits: TraceZipLimi
   };
 }
 
-/** Read a trace from disk: a regular file, size-checked BEFORE it is read into memory. */
+/**
+ * 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 {
-  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);
+  return traceFromRead(readFileOnce(file, limits.maxZipBytes), file, limits);
 }