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

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

@@ -0,0 +1,68 @@
+/**
+ * How a trace target reads in Gherkin: `[<accessible name>] <element type>` plus an optional
+ * `in [<scope name>] <container>` (DOS-14.5, G3). The words are the documented sungen forms, so a
+ * derived `.free.feature` normalizes back to exactly the contract steps the trace produced.
+ *
+ *   name       the accessible name, dynamic parts normalized, private-use glyphs (icon fonts, R4)
+ *              stripped, brackets and quotes made safe for the bracket grammar
+ *   fallback   no usable name (a `getByText` on a <p>, a missing target): the text the test
+ *              itself located by, else the element's text, else the role — always `low` (R3)
+ */
+import { normalizeShownText } from './data-normalize';
+import type { TargetFacts, TargetIdentity } from './trace/target-identity';
+
+const TYPE_OF: Record<string, string> = {
+  button: 'button', link: 'link', textbox: 'field', searchbox: 'search', combobox: 'dropdown', listbox: 'dropdown',
+  checkbox: 'checkbox', radio: 'radio', switch: 'toggle', heading: 'heading', spinbutton: 'field', slider: 'slider',
+  tab: 'tab', img: 'image', dialog: 'dialog', alertdialog: 'dialog', alert: 'alert', row: 'row', cell: 'text',
+  listitem: 'item', option: 'option', menuitem: 'menu-item', status: 'message', table: 'table', list: 'list',
+  navigation: 'region', region: 'region', form: 'form', article: 'card', progressbar: 'progressbar', tooltip: 'tooltip',
+};
+const CONTAINER_OF: Record<string, string> = {
+  row: 'row', listitem: 'list-item', list: 'list', table: 'table', grid: 'table', treegrid: 'table', dialog: 'dialog',
+  alertdialog: 'dialog', form: 'form', group: 'group', radiogroup: 'group', article: 'card', tabpanel: 'panel',
+  menu: 'menu', menubar: 'menu',
+};
+
+/** Private-use code points (icon-font glyphs) are part of the identity but not of what a reader sees. */
+const PRIVATE_USE = /[-]/g;
+
+export function safeRefText(text: string): string {
+  return normalizeShownText(text.replace(PRIVATE_USE, '').replace(/\s+/g, ' ').trim())
+    .replace(/\[/g, '(').replace(/\]/g, ')').replace(/"/g, "'");
+}
+
+export const elementType = (role: string): string => TYPE_OF[role] ?? 'text';
+
+/** The text a locator itself pins (`internal:text="Hi"`, `internal:label="Email"i`, a test id), if any. */
+export function refFromSelector(selector: string | undefined): string {
+  if (!selector) return '';
+  const tail = selector.split(' >> ').filter((p) => !/^(nth=|visible=|internal:control=enter-frame)/.test(p)).pop() ?? '';
+  const quoted = /^internal:(?:text|label|has-text)="((?:[^"\\]|\\.)*)"[is]?$/.exec(tail);
+  if (quoted) return quoted[1].replace(/\\"/g, '"');
+  const attr = /^internal:(?:testid|attr)=\[[\w-]+="((?:[^"\\]|\\.)*)"[is]?\]$/.exec(tail);
+  if (attr) return attr[1];
+  const role = /^internal:role=([a-z]+)(?:\[name="((?:[^"\\]|\\.)*)"[is]?\])?/.exec(tail);
+  if (role) return role[2] ?? role[1];
+  return tail.replace(/^css=/, '');
+}
+
+export interface RenderedTarget { text: string; low?: string }
+
+/** `[Name] type in [Scope] container`, and why it is low when it is. */
+export function renderTarget(identity: TargetIdentity | undefined, facts: TargetFacts | undefined, selector: string | undefined): RenderedTarget {
+  const role = identity?.role ?? 'generic';
+  let name = safeRefText(identity?.name ?? '');
+  let low = identity?.identityConfidence === 'high' ? undefined : (identity?.reasons.join(', ') || 'no target identity');
+  if (!name) {
+    name = safeRefText(refFromSelector(selector) || facts?.text?.slice(0, 60) || role);
+    low = low ?? 'no accessible name';
+  }
+  const scope = identity?.scope && identity.identityConfidence === 'high'
+    ? ` in [${safeRefText(identity.scope.name)}] ${CONTAINER_OF[identity.scope.role] ?? 'region'}` : '';
+  return { text: `[${name}] ${elementType(role)}${scope}`, ...(low ? { low } : {}) };
+}
+
+/** Two identities name the same element (used to drop a focus click before a fill). */
+export const sameTarget = (a: TargetIdentity | undefined, b: TargetIdentity | undefined): boolean =>
+  !!a && !!b && a.role === b.role && a.name === b.name && JSON.stringify(a.scope ?? null) === JSON.stringify(b.scope ?? null);

package/src/contract/resolve-unit-trace-identities.ts

@@ -0,0 +1,58 @@
+/**
+ * `contract check --trace`: before the verdict is built, ask the registered `traceIdentity`
+ * resolver (driver-ui — a real browser) about every target of the unit's admissible traces and
+ * cache the answers (DOS-14.5). The verdict itself never calls a browser; it reads the cache, so
+ * the CLI and the Claude Code guard keep building the same verdict from the same files.
+ *
+ * What it reports is split for QA (#966): a WARNING only when something needs attention — no
+ * resolver, a mobile project, a target the browser could not name (its steps stay opaque). "Every
+ * target was already known" and "N new targets identified" are information, in plain words.
+ */
+import { capabilityRegistry } from '../capabilities/registry';
+import { readCapabilities } from '../harness/capability';
+import { MOBILE_NOT_SUPPORTED } from './build-trace-conformance';
+import { loadContractScenarios } from './normalize-feature-steps';
+import { collectScenarioEvidence } from './trace/collect-trace-evidence';
+import { readIdentityCache } from './trace/identity-cache';
+import { unitContract } from './trace/trace-freshness';
+import type { TraceIdentityResolver } from './trace/target-identity';
+import { resolveWithDriver } from './trace/trace-identity-resolution';
+
+export interface TraceIdentityOutcome { warnings: string[]; info: string[] }
+
+/** The first registered capability that can resolve trace identities (UI: driver-ui), if any. */
+export function registeredTraceResolver(): TraceIdentityResolver | undefined {
+  return capabilityRegistry.all().find((c) => typeof c.traceIdentity === 'function')?.traceIdentity;
+}
+
+export async function traceIdentityOutcome(projectRoot: string, unit: { name: string; dir: string }, resolver = registeredTraceResolver()): Promise<TraceIdentityOutcome> {
+  const none: TraceIdentityOutcome = { warnings: [], info: [] };
+  const traced = loadContractScenarios(unit.dir, unit.name).filter((s) => s.implementation !== 'compiled');
+  if (!traced.length) return none;
+  if ((readCapabilities(projectRoot).platform ?? '').toLowerCase() === 'mobile') return { warnings: [MOBILE_NOT_SUPPORTED], info: [] };
+  if (!resolver) return { warnings: ['no trace identity resolver is registered (install @sungen/driver-ui) — every target identity stays low, so nothing can match'], info: [] };
+  const evidence = collectScenarioEvidence(projectRoot, new Set(traced.map((s) => s.id)), unitContract(projectRoot, unit));
+  const traces = [...evidence.runs.values()].flat().filter((r) => r.status === 'admissible' && r.trace).map((r) => r.trace!);
+  if (!traces.length) return none;
+  const r = await resolveWithDriver(projectRoot, traces, resolver);
+  const { cache } = readIdentityCache(projectRoot);
+  const total = r.keys.length;
+  const unnamed = r.keys.filter((k) => cache.entries.get(k)?.identityConfidence !== 'high').length;
+  const blocked = r.blockedRequests ? `; the replayed pages tried ${r.blockedRequests} request(s), all blocked` : '';
+  const known = total - r.asked;
+  const info = r.asked
+    ? `trace identity: ${r.asked} new target(s) identified in a real browser (${r.resolver})${known ? `, ${known} already known` : ''}${blocked}`
+    : `trace identity: all ${total} target(s) were already identified (identity cache) — nothing new to resolve`;
+  const warnings = unnamed
+    ? [`trace identity: ${unnamed} of ${total} target(s) could not be identified (no unique accessible name) — the steps on them stay opaque, for QA to review, until the test targets a unique, named element`]
+    : [];
+  return { warnings, info: [info] };
+}
+
+/**
+ * What `contract check --trace` adds to the verdict's warnings: only what needs attention (#966).
+ * The plain-words information is `traceIdentityOutcome(...).info`.
+ */
+export async function resolveUnitTraceIdentities(projectRoot: string, unit: { name: string; dir: string }, resolver = registeredTraceResolver()): Promise<string[]> {
+  return (await traceIdentityOutcome(projectRoot, unit, resolver)).warnings;
+}

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

@@ -0,0 +1,178 @@
+/**
+ * Which recorded traces speak for which scenario (DOS-14.6): run records → their JSON reports →
+ * each test's final attempt → its trace (zip limits + version gate) → the binding checks.
+ *
+ *   admissible     final attempt passed, trace read, every binding link holds
+ *   inconclusive   final attempt did not pass                                  (warning)
+ *   unproven       no run record, no test, no trace                            (hard for free / impl:code)
+ *   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 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';
+
+export type RunStatus = 'admissible' | 'inconclusive' | 'unproven' | 'refused' | 'unsupported';
+export interface TraceRun {
+  scenarioId: string;
+  status: RunStatus;
+  reason?: string;
+  test?: ReportTest;
+  result?: ReportResult;
+  record?: RunRecord;
+  trace?: ParsedTrace;
+  /** Project-relative test file (from the run record), once bound. */
+  specFile?: string;
+}
+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-free/ (or test-results/) — run the free tests with their own config: outputDir 'test-results-free', trace: 'on' and the sungen run-record reporter";
+
+/** `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;
+}
+
+/**
+ * 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, 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 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 = 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, 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). 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, 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;
+    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 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(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, contract));
+    }
+  }
+  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`;
+}
+
+/** 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) {
+    // 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/identity-cache.ts

@@ -0,0 +1,61 @@
+/**
+ * The driver's identity answers, memoized per replayed snapshot: `.sungen/trace-identity/identities.json`.
+ *
+ * Core cannot run a browser, but the contract verdict (and the Claude Code guard that rebuilds it)
+ * must be a synchronous function of what is on disk. So `sungen contract check --trace` /
+ * `contract derive` ask `@sungen/driver-ui` once and keep each answer under the sha256 of the EXACT
+ * HTML it judged (target marker included). On read:
+ *
+ *   - a malformed file, an unknown key, an entry that is not well-formed → the whole file is ignored
+ *   - an entry is only ever looked up by the hash of HTML core rendered itself from the trace, so a
+ *     changed snapshot can never inherit an old answer
+ *   - anything not found → core's heuristic, which is `low`, which is never `match`
+ *
+ * This file is derived data, like `.sungen/reports`: deleting it costs a re-resolve, never a pass.
+ */
+import * as fs from 'fs';
+import * as path from 'path';
+import { TRUSTED_RESOLVER, validIdentityResult, TraceIdentityResult } from './target-identity';
+
+export const IDENTITY_CACHE_SCHEMA = 1;
+/** A driver answer plus the browser build that gave it. */
+export type CachedIdentity = Omit<TraceIdentityResult, 'key'> & { browser: string };
+export interface IdentityCache { resolver: string; entries: Map<string, CachedIdentity> }
+
+const FILE_KEYS = new Set(['schema', 'resolver', 'entries']);
+const SHA256 = /^[0-9a-f]{64}$/;
+
+export const identityCachePath = (projectRoot: string): string => path.join(projectRoot, '.sungen', 'trace-identity', 'identities.json');
+
+/** The cache, or an empty one with a reason when there is nothing trustworthy to read. */
+export function readIdentityCache(projectRoot: string): { cache: IdentityCache; problem?: string } {
+  const empty: IdentityCache = { resolver: '', entries: new Map() };
+  const file = identityCachePath(projectRoot);
+  if (!fs.existsSync(file)) return { cache: empty };
+  let raw: unknown;
+  try { raw = JSON.parse(fs.readFileSync(file, 'utf8')); } catch { return { cache: empty, problem: `${path.basename(file)} is not JSON — ignored` }; }
+  const bad = (why: string) => ({ cache: empty, problem: `${path.basename(file)} ${why} — ignored` });
+  if (!raw || typeof raw !== 'object' || Array.isArray(raw)) return bad('is not an object');
+  const doc = raw as Record<string, unknown>;
+  if (Object.keys(doc).some((k) => !FILE_KEYS.has(k))) return bad('has an unknown key');
+  if (doc.schema !== IDENTITY_CACHE_SCHEMA || typeof doc.resolver !== 'string' || !doc.entries || typeof doc.entries !== 'object') return bad('is not schema 1');
+  if (!TRUSTED_RESOLVER.test(doc.resolver)) return bad(`was not written by the driver-ui resolver ("${doc.resolver.slice(0, 40)}")`);
+  const entries = new Map<string, CachedIdentity>();
+  for (const [sha, value] of Object.entries(doc.entries as Record<string, unknown>)) {
+    const { browser, ...answer } = (value && typeof value === 'object' ? value : {}) as Record<string, unknown>;
+    const ok = SHA256.test(sha) && typeof browser === 'string' && browser.length > 0 && browser.length <= 100 ? validIdentityResult({ ...answer, key: sha }) : null;
+    if (!ok) return bad(`has a malformed entry (${sha.slice(0, 12)})`);
+    const { key: _key, ...rest } = ok;
+    entries.set(sha, { ...rest, browser: browser as string });
+  }
+  return { cache: { resolver: doc.resolver, entries } };
+}
+
+/** Write the cache with exactly `entries` (callers merge; answers are keyed by the HTML they judged). */
+export function writeIdentityCache(projectRoot: string, resolver: string, entries: Map<string, CachedIdentity>): string {
+  const file = identityCachePath(projectRoot);
+  fs.mkdirSync(path.dirname(file), { recursive: true });
+  const sorted = Object.fromEntries([...entries.entries()].sort(([a], [b]) => a.localeCompare(b)));
+  fs.writeFileSync(file, `${JSON.stringify({ schema: IDENTITY_CACHE_SCHEMA, resolver, entries: sorted }, null, 2)}\n`);
+  return file;
+}

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

@@ -0,0 +1,77 @@
+/**
+ * Playwright's JSON report → each test's attempts, and which one may speak (DOS-14.6; phase 07
+ * criteria 3–5). Traces are mapped THROUGH the report — `merge-reports` renames trace files to
+ * `resources/<sha1>.zip`, so a directory name is never trusted to say which test a trace is.
+ *
+ *   the final attempt (highest retry) passed, with a trace   admissible (binding still to check)
+ *   the final attempt did not pass                           inconclusive
+ *   the final attempt has no trace attachment                unproven
+ *
+ * A test's scenario id is its first tag that reads as an id (`@VP-LOGIN-001`), else the title's
+ * 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;
+  /** 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);
+const arr = (v: unknown): unknown[] => (Array.isArray(v) ? v : []);
+
+function* specsOf(suite: unknown): Generator<Record<string, unknown>> {
+  if (!isObj(suite)) return;
+  for (const s of arr(suite.specs)) if (isObj(s)) yield s;
+  for (const c of arr(suite.suites)) yield* specsOf(c);
+}
+
+function resultOf(r: unknown): ReportResult | null {
+  if (!isObj(r) || !Number.isInteger(r.retry) || typeof r.status !== 'string') return null;
+  const trace = arr(r.attachments).find((a) => isObj(a) && a.name === 'trace' && typeof a.path === 'string') as { path: string } | undefined;
+  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 (`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(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;
+      for (const t of arr(spec.tests)) {
+        if (!isObj(t)) continue;
+        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, ...configRoot,
+        });
+      }
+    }
+  }
+  return out;
+}
+
+export function scenarioIdOfTest(title: string, tags: string[]): string {
+  const tag = tags.map((t) => t.replace(/^@/, '')).find(isIdLike);
+  if (tag) return tag.toUpperCase();
+  const lead = title.match(/^\s*([A-Za-z][A-Za-z0-9.-]*)/)?.[1];
+  return lead && isIdLike(lead) ? lead.toUpperCase() : title.replace(/\s+/g, ' ').trim();
+}
+
+export function finalAttempt(t: ReportTest): { result?: ReportResult; admissibility: Admissibility; reason?: string } {
+  const result = t.results[t.results.length - 1];
+  if (!result) return { admissibility: 'unproven', reason: 'the report has no attempt for this test' };
+  if (result.status !== 'passed') return { result, admissibility: 'inconclusive', reason: `the final attempt (retry ${result.retry}) did not pass (${result.status})` };
+  if (!result.tracePath) return { result, admissibility: 'unproven', reason: `no trace for the final attempt (retry ${result.retry}) — free / impl:code tests need trace: 'on'` };
+  return { result, admissibility: 'admissible' };
+}