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

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

@@ -0,0 +1,98 @@
+/**
+ * One trace intent step → one sungen Gherkin sentence (without its keyword), in the documented
+ * forms the contract normalizer reads (DOS-14.1): `fill [T] field with {{v}}`, `see [T] heading
+ * with text "x"`, `see the url matches "re"`, `do not see [T] dialog`, `see [T] checkbox is checked`…
+ * A check outside that vocabulary still renders (verbatim expression words) and normalizes to the
+ * `unknown` matcher — which the ladder never calls `match` unless the sentence is identical.
+ */
+import { normalizeShownText, normalizeValue, TestDataIndex } from './data-normalize';
+import { isSensitiveTarget, REDACTED } from './field-semantic-redaction';
+import type { IntentStep } from './trace/trace-steps';
+
+export interface SentenceContext {
+  index: TestDataIndex;
+  /** Raw values typed into credential fields — scrubbed from everything written. */
+  secrets: Set<string>;
+}
+
+const str = (v: unknown): string => (typeof v === 'string' ? v : v === undefined || v === null ? '' : String(v));
+const quote = (v: string): string => `"${v.replace(/"/g, "'").replace(/\r?\n/g, '\\n')}"`;
+
+/** A value as the step writes it: a whole `{{ref}}` bare, anything else quoted. */
+function valueText(raw: string, ctx: SentenceContext, sensitive: boolean): string {
+  const ref = ctx.index.byValue.get(raw);
+  if (ref) return `{{${ref}}}`;
+  if (sensitive) { if (raw) ctx.secrets.add(raw); return REDACTED; }
+  const v = normalizeValue(raw, ctx.index);
+  return /^\{\{[^}]+\}\}$/.test(v) ? v : quote(v);
+}
+
+function pathOf(url: string): string {
+  try { const u = new URL(url); return /^https?:$/.test(u.protocol) ? `${u.pathname}${u.search}` : url; } catch { return url; }
+}
+
+function selectValues(params: Record<string, unknown>): string {
+  const opts = Array.isArray(params.options) ? params.options : [];
+  return opts.map((o) => (o && typeof o === 'object' ? str((o as Record<string, unknown>).valueOrLabel ?? (o as Record<string, unknown>).value ?? (o as Record<string, unknown>).label ?? (o as Record<string, unknown>).index) : str(o))).join(' | ');
+}
+
+export function actionSentence(step: IntentStep, target: string, ctx: SentenceContext, sensitive: boolean): string {
+  const p = step.params;
+  switch (step.method) {
+    case 'goto': return `User is on [${pathOf(normalizeShownText(str(p.url)))}] page`;
+    case 'fill': return `User fill ${target} with ${valueText(str(p.value), ctx, sensitive)}`;
+    case 'type': return `User fill ${target} with ${valueText(str(p.text), ctx, sensitive)}`;
+    case 'click': case 'tap': return `User click ${target}`;
+    case 'dblclick': return `User double click ${target}`;
+    case 'check': return `User check ${target}`;
+    case 'uncheck': return `User uncheck ${target}`;
+    case 'hover': return `User hover ${target}`;
+    case 'selectOption': return `User select ${target} with ${valueText(selectValues(p), ctx, false)}`;
+    case 'press': return `User press ${quote(str(p.key))} on ${target}`;
+    case 'setInputFiles': {
+      const files = Array.isArray(p.payloads) ? p.payloads.map((x) => str((x as Record<string, unknown>)?.name)) : Array.isArray(p.localPaths) ? p.localPaths.map((x) => str(x).split(/[\\/]/).pop() ?? '') : [];
+      return `User fill ${target.replace(/\] \S+/, '] uploader')} with ${quote(files.join(' | '))}`;
+    }
+    case 'keyboardPress': return `User press ${quote(str(p.key))} key`;
+    default: return `User type ${valueText(str(p.text), ctx, false)} on the keyboard`;
+  }
+}
+
+interface Expected { kind: 'text' | 'regex' | 'none'; value: string }
+function expectedOf(p: Record<string, unknown>): Expected {
+  const list = Array.isArray(p.expectedText) ? (p.expectedText as Array<Record<string, unknown>>) : [];
+  if (list.length && list.every((e) => typeof e?.regexSource === 'string')) return { kind: 'regex', value: list.map((e) => str(e.regexSource)).join(' | ') };
+  if (list.length) return { kind: 'text', value: list.map((e) => str(e.string ?? e.regexSource)).join(' | ') };
+  if (typeof p.expectedNumber === 'number') return { kind: 'text', value: String(p.expectedNumber) };
+  return { kind: 'none', value: '' };
+}
+
+const STATES: Record<string, string> = { 'to.be.checked': 'checked', 'to.be.enabled': 'enabled', 'to.be.disabled': 'disabled', 'to.be.focused': 'focused', 'to.be.empty': 'empty', 'to.be.editable': 'editable', 'to.be.attached': 'attached' };
+
+export function assertSentence(step: IntentStep, target: string): string {
+  const p = step.params;
+  const expr = str(p.expression);
+  const not = p.isNot === true;
+  const e = expectedOf(p);
+  const shown = (v: string): string => quote(normalizeShownText(v));
+  if (expr === 'to.have.url' || expr === 'to.have.title') {
+    const subject = expr === 'to.have.url' ? 'url' : 'title';
+    return `User see the ${subject} ${e.kind === 'regex' ? (not ? 'does not match' : 'matches') : not ? 'is not' : 'is'} ${shown(e.value)}`;
+  }
+  if (expr === 'to.be.visible') return not ? `User do not see ${target}` : `User see ${target}`;
+  if (expr === 'to.be.hidden') return not ? `User see ${target}` : `User see ${target} is hidden`;
+  if (STATES[expr]) return `User see ${target} is ${not ? 'not ' : ''}${STATES[expr]}`;
+  if (expr === 'to.have.text' || expr === 'to.contain.text') {
+    if (e.kind === 'regex') return `User see ${target} ${not ? 'does not match' : 'matches'} ${shown(e.value)}`;
+    if (expr === 'to.contain.text') return `User see ${target} ${not ? 'does not contain' : 'contains'} ${shown(e.value)}`;
+    return `User see ${target} ${not ? 'does not have text' : 'with text'} ${shown(e.value)}`;
+  }
+  if (expr === 'to.have.value' || expr === 'to.have.values') return `User see ${target} ${not ? 'does not have value' : 'has value'} ${shown(e.value)}`;
+  if (expr === 'to.have.count') return `User see ${target} ${not ? 'does not have' : 'has'} ${shown(e.value)} items`;
+  const words = expr.replace(/^to\./, '').replace(/\./g, ' ').replace(/^have /, 'has ').replace(/^be /, 'is ');
+  return `User see ${target} ${not ? 'not ' : ''}${words}${e.kind === 'none' ? '' : ` ${shown(e.value)}`}`;
+}
+
+/** The value typed into a credential field is sensitive even when the field's name is not. */
+export const sensitiveStep = (step: IntentStep, facts: Parameters<typeof isSensitiveTarget>[0], name?: string): boolean =>
+  (step.method === 'fill' || step.method === 'type') && isSensitiveTarget(facts, name);

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,35 @@
+/**
+ * `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.
+ */
+import * as fs from 'fs';
+import { capabilityRegistry } from '../capabilities/registry';
+import { readCapabilities } from '../harness/capability';
+import { MOBILE_NOT_SUPPORTED } from './build-trace-conformance';
+import { lockPathFor } from './contracts-lock-file';
+import { contractFeatureFiles, loadContractScenarios } from './normalize-feature-steps';
+import { collectScenarioEvidence } from './trace/collect-trace-evidence';
+import type { TraceIdentityResolver } from './trace/target-identity';
+import { resolveWithDriver } from './trace/trace-identity-resolution';
+
+const mtimeMs = (f: string): number => { try { return fs.statSync(f).mtimeMs; } catch { return 0; } };
+
+/** 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 resolveUnitTraceIdentities(projectRoot: string, unit: { name: string; dir: string }, resolver = registeredTraceResolver()): Promise<string[]> {
+  const traced = loadContractScenarios(unit.dir, unit.name).filter((s) => s.implementation !== 'compiled');
+  if (!traced.length) return [];
+  if ((readCapabilities(projectRoot).platform ?? '').toLowerCase() === 'mobile') return [MOBILE_NOT_SUPPORTED];
+  if (!resolver) return ['no trace identity resolver is registered (install @sungen/driver-ui) — every target identity stays low, so nothing can match'];
+  const notBefore = Math.max(mtimeMs(lockPathFor(unit.dir)), ...contractFeatureFiles(unit.dir, unit.name).map(mtimeMs));
+  const evidence = collectScenarioEvidence(projectRoot, new Set(traced.map((s) => s.id)), notBefore);
+  const traces = [...evidence.runs.values()].flat().filter((r) => r.status === 'admissible' && r.trace).map((r) => r.trace!);
+  if (!traces.length) return [];
+  const r = await resolveWithDriver(projectRoot, traces, resolver);
+  return [`trace identity: ${r.asked} target(s) resolved by ${r.resolver || 'the cache'}${r.blockedRequests ? `, ${r.blockedRequests} replay request(s) blocked` : ''}`];
+}

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

@@ -0,0 +1,109 @@
+/**
+ * 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)
+ *
+ * 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 { bindTrace } from './trace-binding';
+import { readTraceFile, ParsedTrace } from './trace-file-reader';
+import { 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[] }
+
+/** 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";
+
+/** 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; }
+}
+
+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 {};
+}
+
+function judge(projectRoot: string, record: RunRecord, test: ReportTest, notBefore: number): 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)` };
+  let trace: ParsedTrace;
+  try { trace = readTraceFile(file); } 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 });
+  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). */
+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 } {
+  const runs: TraceRun[] = [];
+  const problems: string[] = [];
+  const inputs: 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; }
+    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; }
+    let tests: ReportTest[];
+    try { tests = readPlaywrightReport(reportFile); } 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);
+      if (!want(id, test)) continue;
+      runs.push(Date.now() > deadline ? { scenarioId: id, test, record, status: 'unproven', reason: OVER_BUDGET } : judge(projectRoot, record, test, notBefore));
+    }
+  }
+  return { runs, problems, inputs, records: records.length };
+}
+
+export function collectScenarioEvidence(projectRoot: string, ids: ReadonlySet<string>, notBefore: number, deadline?: number): ScenarioEvidence {
+  const found = collectRuns(projectRoot, (id) => ids.has(id), notBefore, deadline);
+  const runs = new Map<string, TraceRun[]>([...ids].map((id) => [id, found.runs.filter((r) => r.scenarioId === id)]));
+  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 });
+  }
+  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/select-final-attempt.ts

@@ -0,0 +1,70 @@
+/**
+ * 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 { 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 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; throws when the file is not a Playwright JSON report at all. */
+export function readPlaywrightReport(file: 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]})`); }
+  if (!isObj(doc) || !Array.isArray(doc.suites)) throw new Error(`${file} is not a Playwright JSON report (no suites)`);
+  const out: ReportTest[] = [];
+  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,
+        });
+      }
+    }
+  }
+  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' };
+}

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

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