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

package/src/contract/classify-trace-conformance.ts

@@ -7,26 +7,43 @@
  *               with that step — identically (fine), weaker (hard), stronger (strengthened), changed
  *               (review); an approved check with no group or no check in its group → assertion-lost
  *   overlays    a step whose target identity is `low` → opaque (review, never match, red-team #4);
- *               an opaque step → opaque with its verbatim text and file:line (contract.opaque-step)
+ *               an opaque step → opaque with its verbatim text and file:line (contract.opaque-step) —
+ *               unless the approved entry lists it as accepted by QA at its sha (#923, opaqueStepSha):
+ *               then a note, not a finding. impl:code: a test.step whose only candidates are opaque is
+ *               left to the overlay (judged on the ladder it could only read "changed"), which names the
+ *               approved step the opaque one replaces
  *   runs        no admissible trace → unproven (all inconclusive → inconclusive) when APPROVED, a
  *               warning while proposed (M5, M6); a trace refused beside an admissible one → a warning;
  *               several admissible traces that fingerprint differently → nondeterministic (worst wins)
  */
 import { classifyScenario, ContractFinding, finding, ScenarioResult, severityOf } from './classify-contract-change';
-import { sameJson } from './contract-hash';
-import type { ContractStep, Implementation, LockEntry, ScenarioClass } from './contract-schema';
+import { canonicalJson, sameJson, sha256Hex } from './contract-hash';
+import type { AcceptedOpaqueStep, ContractStep, Implementation, LockEntry, OpaqueStep, ScenarioClass } from './contract-schema';
 import { compareAsserts } from './oracle-strength';
+import { clip, RenderedStep } from './render-free-gherkin';
 import type { TraceRun } from './trace/collect-trace-evidence';
 import type { TraceFingerprint } from './trace/trace-fingerprint';
 
-/** `warnings` never change the verdict: a not-yet-approved scenario's trace problems, unused traces. */
-export interface TraceOutcome { class: ScenarioClass; findings: ContractFinding[]; hashes: string[]; runs: string[]; warnings: string[] }
+/**
+ * `warnings` never change the verdict: a not-yet-approved scenario's trace problems, unused traces, an
+ * accepted opaque step. `opaque`: every opaque step of the admissible traces, accepted or not.
+ */
+export interface TraceOutcome { class: ScenarioClass; findings: ContractFinding[]; hashes: string[]; runs: string[]; warnings: string[]; opaque: OpaqueStep[] }
 
 /** What an unjudgeable scenario becomes: hard when QA locked it (approved), a warning while it is proposed. */
 export function notJudged(id: string, approved: boolean, cls: 'unproven' | 'inconclusive', reasons: string[]): TraceOutcome {
   return approved
-    ? { class: cls, findings: reasons.map((r) => finding(cls, r)), hashes: [], runs: [], warnings: [] }
-    : { class: 'proposed', findings: [], hashes: [], runs: [], warnings: reasons.map((r) => `${id} (not approved yet, so a warning): ${r}`) };
+    ? { class: cls, findings: reasons.map((r) => finding(cls, r)), hashes: [], runs: [], warnings: [], opaque: [] }
+    : { class: 'proposed', findings: [], hashes: [], runs: [], warnings: reasons.map((r) => `${id} (not approved yet, so a warning): ${r}`), opaque: [] };
+}
+
+/**
+ * The sha a QA acceptance binds to (#923): the opaque step as rendered — its verbatim line or request,
+ * check or step, the `test.step` it sits in — and as normalized, with the implementation path. Any
+ * change to the step gives another sha, so the old acceptance no longer covers it.
+ */
+export function opaqueStepSha(implementation: Implementation, r: RenderedStep, step: ContractStep | undefined): string {
+  return sha256Hex(canonicalJson({ implementation, kind: r.kind, group: r.group ?? null, verbatim: r.opaque?.verbatim ?? null, step: step ?? null })).slice(0, 16);
 }
 
 /** How a low target identity opens its finding — `next` reads it to offer `contract check --trace`. */
@@ -35,19 +52,41 @@ export const LOW_IDENTITY_FINDING = 'target identity is low';
 const worstOf = (findings: ContractFinding[], start: ScenarioClass = 'match'): ScenarioClass =>
   findings.reduce<ScenarioClass>((acc, f) => (severityOf(f.class as ScenarioClass) > severityOf(acc) ? f.class as ScenarioClass : acc), start);
 
-function overlays(fp: TraceFingerprint, used?: Set<number>): ContractFinding[] {
-  const out: ContractFinding[] = [];
+type Judged = { findings: ContractFinding[]; opaque: OpaqueStep[] };
+
+/** An approved step as a reader sees it: `see [My Account] heading with text "My Account"`. */
+function approvedStepText(s: ContractStep): string {
+  const refs = [s.target?.ref, ...(s.target?.also ?? [])].filter((r): r is string => r !== undefined);
+  const values = (s.kind === 'assert' ? s.expected : s.value)?.split(' | ') ?? [];
+  let r = 0;
+  let v = 0;
+  return s.verb.replace(/\[\]/g, () => `[${refs[r++] ?? ''}]`).replace(/\{\}/g, () => (v < values.length ? `"${values[v++]}"` : '{}'));
+}
+
+function overlays(
+  fp: TraceFingerprint, implementation: Implementation, accepted: readonly AcceptedOpaqueStep[], used?: Set<number>, replaces?: ReadonlyMap<number, string>,
+): Judged {
+  const findings: ContractFinding[] = [];
+  const opaque: OpaqueStep[] = [];
   fp.rendered.forEach((r, i) => {
     if (used && !used.has(i)) return;
-    if (r.opaque) out.push(finding('opaque', `"${r.opaque.verbatim}"${r.opaque.where ? ` at ${r.opaque.where}` : ''} — ${r.kind === 'assert' ? 'a check' : 'a step'} sungen cannot compare; QA reviews it`, i + 1));
-    else if (r.low) out.push(finding('opaque', `${LOW_IDENTITY_FINDING} (${r.low}) — cannot prove "${r.sentence}" acts on the approved element`, i + 1));
+    if (r.opaque) {
+      const sha = opaqueStepSha(implementation, r, fp.steps[i]);
+      const isAccepted = accepted.some((a) => a.step === i + 1 && a.sha === sha);
+      const instead = replaces?.get(i);
+      opaque.push({ step: i + 1, sha, kind: r.kind, verbatim: r.opaque.verbatim, ...(r.opaque.where ? { where: r.opaque.where } : {}), ...(instead ? { replaces: instead } : {}), accepted: isAccepted });
+      if (!isAccepted) {
+        findings.push(finding('opaque', `"${r.opaque.verbatim}"${r.opaque.where ? ` at ${r.opaque.where}` : ''} — ${r.kind === 'assert' ? 'a check' : 'a step'} sungen cannot compare; QA reviews it${instead ? ` — replaces approved ${instead}` : ''}`, i + 1));
+      }
+    } else if (r.low) findings.push(finding('opaque', `${LOW_IDENTITY_FINDING} (${r.low}) — cannot prove "${r.sentence}" acts on the approved element`, i + 1));
   });
-  return out;
+  return { findings, opaque };
 }
 
-function implCodeFindings(entry: LockEntry, fp: TraceFingerprint): { findings: ContractFinding[]; used: Set<number> } {
+function implCodeFindings(entry: LockEntry, fp: TraceFingerprint): { findings: ContractFinding[]; used: Set<number>; replaces: Map<number, string> } {
   const findings: ContractFinding[] = [];
   const used = new Set<number>();
+  const replaces = new Map<number, string>();
   const taken = new Set<number>();
   entry.steps.forEach((locked, i) => {
     const g = fp.groups.findIndex((x, gi) => !taken.has(gi) && sameJson(x.titleStep, locked));
@@ -68,6 +107,13 @@ function implCodeFindings(entry: LockEntry, fp: TraceFingerprint): { findings: C
       return;
     }
     candidates.forEach((m) => used.add(m));
+    // Only steps sungen cannot compare implement this approved step: the overlay sends them to QA's
+    // review (#923), naming the approved step. On the ladder they could only read "changed", which
+    // re-approving never clears.
+    if (candidates.every((m) => fp.rendered[m].opaque)) {
+      for (const m of candidates) replaces.set(m, `step ${i + 1} "${clip(approvedStepText(locked))}"`);
+      return;
+    }
     if (locked.kind === 'action') { findings.push(finding('hash-changed', `the code for "${locked.verb}" does something else: "${fp.rendered[candidates[0]].sentence}"`, i + 1)); return; }
     const judged = candidates.map((m) => compareAsserts(locked, fp.steps[m] as ContractStep));
     const rank = (k: string): number => (k === 'oracle-weakened' ? 0 : k === 'review' ? 1 : 2);
@@ -75,18 +121,21 @@ function implCodeFindings(entry: LockEntry, fp: TraceFingerprint): { findings: C
     findings.push(finding(best.class === 'review' ? 'hash-changed' : best.class, best.detail, i + 1));
   });
   fp.groups.forEach((g, gi) => { if (!taken.has(gi)) findings.push(finding('hash-changed', `test.step "${g.title}" implements no approved step`)); });
-  return { findings, used };
+  return { findings, used, replaces };
 }
 
-function classifyOne(id: string, implementation: Implementation, entry: LockEntry, fp: TraceFingerprint): ContractFinding[] {
+function classifyOne(id: string, implementation: Implementation, entry: LockEntry, fp: TraceFingerprint): Judged {
+  const accepted = entry.acceptedOpaque ?? [];
   if (implementation === 'impl:code') {
-    const { findings, used } = implCodeFindings(entry, fp);
-    return [...findings, ...overlays(fp, used)];
+    const { findings, used, replaces } = implCodeFindings(entry, fp);
+    const o = overlays(fp, implementation, accepted, used, replaces);
+    return { findings: [...findings, ...o.findings], opaque: o.opaque };
   }
   const ladder: ScenarioResult = classifyScenario(id, entry, {
     id, implementation, steps: fp.steps, hash: fp.hash, source: { file: '', name: id, hasId: true, lines: [], outline: false },
   });
-  return [...ladder.findings, ...overlays(fp)];
+  const o = overlays(fp, implementation, accepted);
+  return { findings: [...ladder.findings, ...o.findings], opaque: o.opaque };
 }
 
 const runLabel = (r: TraceRun): string => `${r.record?.runId ?? '?'}#${r.result?.retry ?? '?'}`;
@@ -104,13 +153,18 @@ export function classifyTraceRuns(
   }
   // A trace that may not speak, beside one that may: the admissible one judges, the other is a warning.
   const warnings = others.map((r) => `${id}: another trace of this scenario was not used — ${r.reason ?? r.status}`);
-  if (!entry) return { class: 'proposed', findings: [], hashes, runs: labels, warnings };
+  if (!entry) return { class: 'proposed', findings: [], hashes, runs: labels, warnings, opaque: [] };
   const perRun = admissible.map((r) => classifyOne(id, implementation, entry, fingerprints.get(r)!));
-  const findings = perRun.flat();
-  let cls = worstOf(perRun.flat());
+  const findings = perRun.flatMap((p) => p.findings);
+  const opaque = [...new Map(perRun.flatMap((p) => p.opaque).map((o) => [`${o.step}:${o.sha}`, o] as const)).values()]
+    .sort((a, b) => a.step - b.step || a.sha.localeCompare(b.sha));
+  for (const o of opaque.filter((x) => x.accepted)) {
+    warnings.push(`${id}: step ${o.step} — opaque ${o.kind === 'assert' ? 'check' : 'step'} "${clip(o.verbatim)}" accepted by QA (decision ${entry.decisionId}), not compared`);
+  }
+  let cls = worstOf(findings);
   if (new Set(hashes).size > 1) {
     findings.push(finding('nondeterministic', `${new Set(hashes).size} different fingerprints across ${admissible.length} runs — the runs took different branches`));
     if (severityOf(cls) <= severityOf('strengthened')) cls = 'nondeterministic';
   }
-  return { class: cls, findings, hashes, runs: labels, warnings };
+  return { class: cls, findings, hashes, runs: labels, warnings, opaque };
 }

package/src/contract/contract-schema.ts

@@ -3,7 +3,7 @@
  *
  *   step   {kind: action|assert, verb, target?:{ref, also?, parent?, nth?}, value?, matcher?, expected?, negated?, table?}
  *   lock   qa/<kind>/<unit>/contracts.lock.yaml → {schema: 1, scenarios: {<scenario id>: LockEntry}}
- *   entry  {hash, steps, implementation, approvedAt, decisionId, humanApproved?}
+ *   entry  {hash, steps, implementation, approvedAt, decisionId, humanApproved?, acceptedOpaque?}
  *
  * A stored entry is checked the way the decision layer checks its records: a wrong type or an
  * UNKNOWN key is an error, because a field outside the hash could carry meaning the hash does not
@@ -49,6 +49,9 @@ export interface ContractScenario {
   source: { file: string; name: string; hasId: boolean; lines: number[]; outline: boolean };
 }
 
+/** A reviewed opaque trace step QA accepted (#923): its 1-based position in the trace's steps and its sha (opaqueStepSha). */
+export interface AcceptedOpaqueStep { step: number; sha: string }
+
 export interface LockEntry {
   hash: string;
   steps: ContractStep[];
@@ -56,8 +59,16 @@ export interface LockEntry {
   approvedAt: string;
   decisionId: string;
   humanApproved?: true;
+  /** Opaque trace steps a QA accepted on a terminal (`contract approve --accept-opaque`) — vouched for by `decisionId`. */
+  acceptedOpaque?: AcceptedOpaqueStep[];
 }
 
+/**
+ * One opaque step of a scenario's trace(s), as `contract check` reports it and `--accept-opaque` shows it.
+ * `replaces` (impl:code): the approved step it stands in for — `step 5 "see [Title] heading"`.
+ */
+export interface OpaqueStep { step: number; sha: string; kind: 'action' | 'assert'; verbatim: string; where?: string; replaces?: string; accepted: boolean }
+
 export const LOCK_SCHEMA = 1;
 export interface ContractLock { schema: typeof LOCK_SCHEMA; scenarios: Record<string, LockEntry> }
 
@@ -88,8 +99,10 @@ export const RULE_OF: Readonly<Partial<Record<FindingClass, string>>> = {
 
 const STEP_KEYS = new Set(['kind', 'verb', 'target', 'value', 'matcher', 'expected', 'negated', 'table']);
 const TARGET_KEYS = new Set(['ref', 'also', 'parent', 'nth']);
-const ENTRY_KEYS = new Set(['hash', 'steps', 'implementation', 'approvedAt', 'decisionId', 'humanApproved']);
+const ENTRY_KEYS = new Set(['hash', 'steps', 'implementation', 'approvedAt', 'decisionId', 'humanApproved', 'acceptedOpaque']);
+const ACCEPTED_KEYS = new Set(['step', 'sha']);
 const HASH_RE = /^[0-9a-f]{12}$/;
+export const OPAQUE_SHA_RE = /^[0-9a-f]{16}$/;
 
 const isObject = (v: unknown): v is Record<string, unknown> => typeof v === 'object' && v !== null && !Array.isArray(v);
 const isStringList = (v: unknown): v is string[] => Array.isArray(v) && v.every((x) => typeof x === 'string');
@@ -118,6 +131,18 @@ export function stepErrors(s: unknown, at: string): string[] {
   return e;
 }
 
+function acceptedOpaqueErrors(v: unknown, at: string): string[] {
+  if (!Array.isArray(v) || !v.length) return [`${at}: acceptedOpaque must be a non-empty list`];
+  return v.flatMap((a, i) => {
+    const where = `${at} acceptedOpaque ${i + 1}`;
+    if (!isObject(a)) return [`${where}: not a mapping`];
+    const e = unknownKeys(a, ACCEPTED_KEYS, where);
+    if (!(Number.isInteger(a.step) && (a.step as number) > 0)) e.push(`${where}: step must be a positive integer`);
+    if (typeof a.sha !== 'string' || !OPAQUE_SHA_RE.test(a.sha)) e.push(`${where}: sha must be 16 hex characters`);
+    return e;
+  });
+}
+
 /** Errors in one stored lock entry (empty = well-formed). The hash itself is checked by the reader. */
 export function lockEntryErrors(raw: unknown, id: string): string[] {
   const at = `scenario ${id}`;
@@ -128,6 +153,10 @@ export function lockEntryErrors(raw: unknown, id: string): string[] {
   if (typeof raw.approvedAt !== 'string' || Number.isNaN(Date.parse(raw.approvedAt))) e.push(`${at}: approvedAt must be an ISO-8601 timestamp`);
   if (typeof raw.decisionId !== 'string' || !DECISION_ID_RE.test(raw.decisionId)) e.push(`${at}: decisionId must be D-<16 hex>`);
   if (raw.humanApproved !== undefined && raw.humanApproved !== true) e.push(`${at}: humanApproved is either true or absent`);
+  if (raw.acceptedOpaque !== undefined) {
+    e.push(...acceptedOpaqueErrors(raw.acceptedOpaque, at));
+    if (raw.humanApproved !== true) e.push(`${at}: acceptedOpaque needs humanApproved: true`);
+  }
   if (!Array.isArray(raw.steps)) e.push(`${at}: steps must be a list`);
   else raw.steps.forEach((s, i) => e.push(...stepErrors(s, `${at} step ${i + 1}`)));
   return e;

package/src/contract/contracts-lock-file.ts

@@ -80,6 +80,7 @@ export function serializeLock(lock: ContractLock): string {
     scenarios[id] = {
       hash: e.hash, implementation: e.implementation, approvedAt: e.approvedAt, decisionId: e.decisionId,
       ...(e.humanApproved === true ? { humanApproved: true as const } : {}),
+      ...(e.acceptedOpaque?.length ? { acceptedOpaque: e.acceptedOpaque.map((a) => ({ step: a.step, sha: a.sha })) } : {}),
       steps: e.steps.map(orderedStep),
     };
   }

package/src/contract/project-contract-blockers.ts

@@ -4,12 +4,14 @@
  * HEAD is read once (one `git ls-tree`, bounded by the caller's timeout). A unit with no lock in the
  * working tree AND none in HEAD has no contract to break and is skipped without parsing anything.
  * Every other unit gets its verdict rebuilt by buildContractVerdict — the same function `contract
- * check` runs — and anything but `pass` blocks. A lock deleted from the working tree still counts
+ * check` runs — and anything but `pass` blocks. Its trace part gets the guard's ~3 s at most:
+ * SUNGEN_TRACE_VERDICT_BUDGET_MS can shorten that here, never lengthen it (#926). A lock deleted from the working tree still counts
  * while HEAD holds it. If git FAILS in a checkout that has .git while a delivered unit has a lock,
  * this throws (GitUnavailableError): the guard asks rather than calling an unverifiable lock clean.
  */
 import * as fs from 'fs';
 import { buildContractVerdict, ContractUnit, VerdictValue } from './build-contract-verdict';
+import { guardTraceBudgetMs } from './build-trace-conformance';
 import { CLI_GIT_TIMEOUT_MS, GitUnavailableError, headSnapshot, posixRel } from './contract-git';
 import { HARD_CLASSES } from './contract-schema';
 import { lockPathFor } from './contracts-lock-file';
@@ -24,7 +26,7 @@ export function contractBlockers(projectRoot: string, units: ContractUnit[], opt
   const out: ContractBlocker[] = [];
   for (const unit of unique) {
     if (!hasWorkingLock(unit) && !snap.blobs?.has(posixRel(projectRoot, lockPathFor(unit.dir)))) continue;
-    const v = buildContractVerdict(projectRoot, unit, { snapshot: snap });
+    const v = buildContractVerdict(projectRoot, unit, { snapshot: snap, traceBudgetMs: guardTraceBudgetMs() });
     if (v.verdict === 'pass') continue;
     const worst = v.scenarios.find((s) => HARD_CLASSES.has(s.class)) ?? v.scenarios.find((s) => s.class === 'hash-changed');
     const headline = worst

package/src/contract/record-contract-approval.ts

@@ -9,13 +9,17 @@
  * The decision goes first: a crash between the two leaves a record without a lock entry, never an
  * entry pointing at nothing. Only `sungen contract approve` calls this after its TTY confirmation;
  * the confirmation itself lives there (approve-contract.ts).
+ *
+ * `--accept-opaque` (#923, accept-opaque-steps.ts) writes the same kind of decision for ONE scenario,
+ * listing it at its hash WITH the opaque steps QA accepted (step + sha); its lock entry is rewritten to
+ * point at that decision and carries the same list, which verify-approval-decisions.ts cross-checks.
  */
 import * as path from 'path';
 import { appendDecision } from '../decisions/append-decision';
 import { isValidScope } from '../decisions/decision-file';
 import type { JsonValue } from '../decisions/decision-schema';
 import { gitUserName } from '../decisions/decision-source';
-import { ContractLock, ContractScenario, LOCK_SCHEMA } from './contract-schema';
+import { AcceptedOpaqueStep, ContractLock, ContractScenario, LOCK_SCHEMA } from './contract-schema';
 import { lockEntryFor, lockPathFor, serializeLock, writeLockFile } from './contracts-lock-file';
 import { assertNoLockSecrets } from './lock-secret-guard';
 
@@ -30,6 +34,18 @@ export interface ApprovalWrite {
 }
 
 export const DEFAULT_APPROVAL_REASON = 'QA reviewed the normalized Gherkin contract';
+export const DEFAULT_OPAQUE_REASON = 'QA reviewed the opaque step(s) sungen cannot compare';
+
+export interface OpaqueAcceptanceWrite {
+  projectRoot: string;
+  unitDir: string;
+  unit: string;
+  /** The scenario as it reads now — its hash equals its approved lock entry's. */
+  scenario: ContractScenario;
+  accepted: AcceptedOpaqueStep[];
+  reason?: string;
+  lock: ContractLock;
+}
 
 /** The decision scope of a unit directory (`screens/login`, `api/flows/pay`…). */
 export function scopeOfUnitDir(projectRoot: string, unitDir: string): string {
@@ -68,3 +84,27 @@ export function recordContractApproval(w: ApprovalWrite): { decisionId: string;
   writeLockFile(lockPathFor(w.unitDir), lock);
   return { decisionId: decision.entry.id, lock };
 }
+
+function lockWithAcceptance(w: OpaqueAcceptanceWrite, decisionId: string, approvedAt: string): ContractLock {
+  const entry = { ...lockEntryFor(w.scenario, decisionId, approvedAt), acceptedOpaque: w.accepted.map((a) => ({ step: a.step, sha: a.sha })) };
+  return { schema: LOCK_SCHEMA, scenarios: { ...w.lock.scenarios, [w.scenario.id]: entry } };
+}
+
+export function recordOpaqueAcceptance(w: OpaqueAcceptanceWrite): { decisionId: string; lock: ContractLock } {
+  const scope = scopeOfUnitDir(w.projectRoot, w.unitDir);
+  assertNoLockSecrets([w.scenario], serializeLock(lockWithAcceptance(w, 'D-0000000000000000', new Date().toISOString())));
+  const sc = w.scenario;
+  const accepted = w.accepted.map((a) => ({ step: a.step, sha: a.sha }));
+  const payload: Record<string, JsonValue> = {
+    unit: w.unit, scenarios: [{ id: sc.id, hash: sc.hash, implementation: sc.implementation, acceptedOpaque: accepted }], removed: [],
+  };
+  const decision = appendDecision(w.projectRoot, scope, {
+    kind: 'contract-approval', anchors: [], visibility: 'internal', valid_from: new Date().toISOString(), payload,
+    text: `Accepted the reviewed opaque step(s) ${[...new Set(accepted.map((a) => a.step))].join(', ')} of ${sc.id} (${w.unit})`,
+    reason: w.reason?.trim() || DEFAULT_OPAQUE_REASON,
+    source: { by: gitUserName(w.projectRoot), where: 'cli' },
+  });
+  const lock = lockWithAcceptance(w, decision.entry.id, decision.entry.valid_from);
+  writeLockFile(lockPathFor(w.unitDir), lock);
+  return { decisionId: decision.entry.id, lock };
+}

package/src/contract/render-free-gherkin.ts

@@ -22,6 +22,11 @@ import { isPageLevel } from './trace/trace-identity-resolution';
 import type { IntentStep } from './trace/trace-steps';
 
 export const CONTROL_CHARS = /[\u0000-\u001f\u007f\u2028\u2029]/g;
+/** Text from a trace or report shown in one line of a finding: control characters dropped, at most `max` characters. */
+export function clip(s: string, max = 120): string {
+  const t = s.replace(CONTROL_CHARS, '');
+  return t.length > max ? `${t.slice(0, max - 1)}\u2026` : t;
+}
 
 export interface ResolvedTarget { identity: TargetIdentity; facts?: TargetFacts }
 export interface RenderedStep {

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

@@ -12,9 +12,12 @@
  */
 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 { bindTrace } from './trace-binding';
-import { readTraceFile, ParsedTrace } from './trace-file-reader';
-import { TraceRejected } from './trace-zip-limits';
+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,26 +35,26 @@ 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-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 } {
+/** Where a report's trace attachment is: the first candidate that exists (read later, opened once). */
+function attachmentPath(projectRoot: string, report: string, p: string): string | null {
   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 };
+    if (fs.existsSync(cand)) return cand;
   }
-  return {};
+  return null;
 }
 
 function judge(projectRoot: string, record: RunRecord, test: ReportTest, notBefore: number): TraceRun {
@@ -59,11 +62,18 @@ function judge(projectRoot: string, record: RunRecord, test: ReportTest, notBefo
   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.report, 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}` };
   }
@@ -75,35 +85,62 @@ function judge(projectRoot: string, record: RunRecord, test: ReportTest, notBefo
 /** 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 } {
+): { runs: TraceRun[]; problems: string[]; inputs: string[]; records: number; seen: Array<{ id: string; title: string }> } {
   const runs: TraceRun[] = [];
   const problems: 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) { 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; }
+    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));
     }
   }
-  return { runs, problems, inputs, records: records.length };
+  return { runs, problems, 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 {
+/** The runs of each scenario id; `names` (id → scenario name) lets a missing test be explained. */
+export function collectScenarioEvidence(
+  projectRoot: string, ids: ReadonlySet<string>, notBefore: number, deadline?: number, names?: ReadonlyMap<string, string>,
+): 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 });
+    if (!list.length) list.push({ scenarioId: id, status: 'unproven', reason: found.records ? noTestFor(id, names?.get(id), found.seen) : 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/select-final-attempt.ts

@@ -32,10 +32,10 @@ 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[] = [];
   for (const top of doc.suites) {