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

package/src/contract/classify-contract-unit.ts

@@ -0,0 +1,47 @@
+/**
+ * Every scenario id of a unit, locked or current, with its ladder class (DOS-14.3, DOS-14.4).
+ *
+ *   approved entry, one current copy      classifyScenario (the ladder)
+ *   approved entry, no current copy       assertion-lost
+ *   approved entry, several copies        assertion-lost — the lock can no longer tell which copy QA
+ *                                         approved, and picking one would let the others hide (M7)
+ *   no approved entry                     proposed (never blocks); a tampered entry counts as none
+ *   Scenario Outline (any lock state)     at least hash-changed: the compiler does not support the
+ *                                         construct, so the contract cannot judge its Examples
+ */
+import { classifyScenario, finding, ScenarioResult, severityOf } from './classify-contract-change';
+import { ContractLock, ContractScenario, isHumanApproved } from './contract-schema';
+
+const OUTLINE = 'Scenario Outline is not supported by the compiler — the contract cannot judge its Examples rows; rewrite it as @cases data';
+
+function withOutlineFinding(r: ScenarioResult): ScenarioResult {
+  const findings = [...r.findings, finding('hash-changed', OUTLINE)];
+  return { ...r, class: severityOf(r.class) >= severityOf('hash-changed') ? r.class : 'hash-changed', findings };
+}
+
+export function classifyUnit(
+  lock: ContractLock | null, current: ContractScenario[], untrusted: ReadonlySet<string> = new Set(),
+): { results: ScenarioResult[]; warnings: string[] } {
+  const groups = new Map<string, ContractScenario[]>();
+  for (const sc of current) groups.set(sc.id, [...(groups.get(sc.id) ?? []), sc]);
+  const approvedIds = Object.entries(lock?.scenarios ?? {}).filter(([id, e]) => isHumanApproved(e) && !untrusted.has(id)).map(([id]) => id);
+  const results: ScenarioResult[] = [];
+  const warnings: string[] = [];
+  for (const id of [...new Set([...approvedIds, ...groups.keys()])].sort((a, b) => a.localeCompare(b, 'en'))) {
+    const entry = lock?.scenarios[id];
+    const copies = groups.get(id) ?? [];
+    const approved = isHumanApproved(entry) && !untrusted.has(id);
+    let mine: ScenarioResult[];
+    if (!approved) {
+      if (copies.length > 1) warnings.push(`scenario id ${id} is used by ${copies.length} scenarios — give each its own ID before approving`);
+      mine = copies.map((c) => ({ id, class: 'proposed', findings: [], file: c.source.file }));
+    } else if (copies.length > 1) {
+      mine = [{ id, class: 'assertion-lost', file: copies[0].source.file, findings: [finding('assertion-lost',
+        `the approved id ${id} is now carried by ${copies.length} scenarios — the lock cannot tell which one QA approved; give each its own ID`)] }];
+    } else {
+      mine = [classifyScenario(id, entry!, copies[0])];
+    }
+    results.push(...(copies.some((c) => c.source.outline) ? mine.map(withOutlineFinding) : mine));
+  }
+  return { results, warnings };
+}

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

@@ -0,0 +1,170 @@
+/**
+ * A free / impl:code scenario's traces against its approved lock entry (DOS-14.5 – 14.6) — the SAME
+ * strength ladder as the Gherkin check (DOS-14.4, oracle-strength.ts), fed from the trace fingerprint.
+ *
+ *   free        classifyScenario(lock entry, fingerprint): equal hash → match, else the ladder
+ *   impl:code   group by group: each approved step must be realized inside the `test.step` titled
+ *               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) —
+ *               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 { 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, 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: [], 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`. */
+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);
+
+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) {
+      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 { findings, opaque };
+}
+
+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));
+    if (g < 0) {
+      findings.push(locked.kind === 'assert'
+        ? finding('assertion-lost', `no test.step implements the approved check "${locked.verb}" (step ${i + 1})`)
+        : finding('hash-changed', `no test.step implements the approved step "${locked.verb}" (step ${i + 1})`));
+      return;
+    }
+    taken.add(g);
+    const members = fp.groups[g].members;
+    const same = members.find((m) => sameJson(fp.steps[m], locked));
+    if (same !== undefined) { used.add(same); return; }
+    const candidates = members.filter((m) => fp.steps[m].kind === locked.kind);
+    if (!candidates.length) {
+      findings.push(locked.kind === 'assert' ? finding('assertion-lost', `the test.step for "${locked.verb}" checks nothing`, i + 1)
+        : finding('hash-changed', `the test.step for "${locked.verb}" does nothing on the page`, i + 1));
+      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);
+    const best = judged.sort((a, b) => rank(b.class) - rank(a.class))[0];
+    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, replaces };
+}
+
+function classifyOne(id: string, implementation: Implementation, entry: LockEntry, fp: TraceFingerprint): Judged {
+  const accepted = entry.acceptedOpaque ?? [];
+  if (implementation === 'impl:code') {
+    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 },
+  });
+  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 ?? '?'}`;
+
+export function classifyTraceRuns(
+  id: string, implementation: Implementation, entry: LockEntry | undefined, runs: TraceRun[], fingerprints: Map<TraceRun, TraceFingerprint>,
+): TraceOutcome {
+  const admissible = runs.filter((r) => r.status === 'admissible' && fingerprints.has(r));
+  const others = runs.filter((r) => !admissible.includes(r));
+  const labels = admissible.map(runLabel);
+  const hashes = admissible.map((r) => fingerprints.get(r)!.hash);
+  if (!admissible.length) {
+    const allInconclusive = others.length > 0 && others.every((r) => r.status === 'inconclusive');
+    return { ...notJudged(id, !!entry, allInconclusive ? 'inconclusive' : 'unproven', others.map((r) => r.reason ?? r.status)), hashes, runs: labels };
+  }
+  // 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, opaque: [] };
+  const perRun = admissible.map((r) => classifyOne(id, implementation, entry, fingerprints.get(r)!));
+  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, opaque };
+}

package/src/contract/contract-git.ts

@@ -0,0 +1,106 @@
+/**
+ * What git HEAD holds under `qa/`, for the contract (DOS-14.4) — with a timeout the caller picks
+ * (≈3 s inside the Claude Code guard, whose own budget is 5 s; 30 s for the CLI).
+ *
+ * Three answers, never confused:
+ *   blobs          one `git ls-tree -r -z HEAD -- qa`: every committed lock and decision with its blob id
+ *   no git         no `.git` at or above the project, or a repository without a first commit
+ *   git FAILED     `.git` is there but git errors, times out, refuses (dubious ownership) or is not
+ *                  installed — reported as `error`, so the caller can refuse to call a lock "clean"
+ *
+ * A file whose working bytes hash to its HEAD blob id IS its committed version: it is read from disk
+ * and needs no `git show`. git runs with fixed arguments, never through a shell.
+ */
+import { execFileSync } from 'child_process';
+import { createHash } from 'crypto';
+import * as fs from 'fs';
+import * as path from 'path';
+
+export const CLI_GIT_TIMEOUT_MS = 30_000;
+export const GUARD_GIT_TIMEOUT_MS = 3_000;
+
+export class GitUnavailableError extends Error {
+  constructor(detail: string) {
+    super(`git is unavailable in a checkout that has .git (${detail}) — the contract lock cannot be compared with HEAD`);
+    this.name = 'GitUnavailableError';
+  }
+}
+
+/** One flat shape: the project compiles without strictNullChecks, where a boolean-tagged union does not narrow. */
+interface GitRun { ok: boolean; out: string; timedOut: boolean; message: string }
+
+function runGit(cwd: string, args: string[], timeoutMs: number): GitRun {
+  try {
+    const out = execFileSync('git', args, { cwd, stdio: ['ignore', 'pipe', 'pipe'], maxBuffer: 64 * 1024 * 1024, timeout: timeoutMs }).toString('utf8');
+    return { ok: true, out, timedOut: false, message: '' };
+  } catch (e) {
+    const err = e as NodeJS.ErrnoException & { signal?: string; stderr?: Buffer };
+    const message = (err.stderr?.toString().trim() || err.message || String(e)).split('\n')[0];
+    return { ok: false, out: '', timedOut: err.code === 'ETIMEDOUT' || err.signal === 'SIGTERM', message };
+  }
+}
+
+function hasDotGit(start: string): boolean {
+  let dir = path.resolve(start);
+  for (let i = 0; i < 40; i++) {
+    if (fs.existsSync(path.join(dir, '.git'))) return true;
+    const parent = path.dirname(dir);
+    if (parent === dir) return false;
+    dir = parent;
+  }
+  return false;
+}
+
+export interface HeadSnapshot {
+  root: string;
+  timeoutMs: number;
+  /** Project-relative path → blob id of each committed lock and decision; null when there is nothing to compare with. */
+  blobs: Map<string, string> | null;
+  /** Set when git FAILED in a checkout that has .git (blobs is then null). */
+  error?: string;
+}
+
+const RECORD = /^\d+ blob ([0-9a-f]+)\t(.+)$/s;
+const KEEP = (p: string): boolean => p.endsWith('/contracts.lock.yaml') || /\/decisions\/[^/]+\.yaml$/.test(p);
+
+export function headSnapshot(root: string, timeoutMs = CLI_GIT_TIMEOUT_MS): HeadSnapshot {
+  const r = runGit(root, ['ls-tree', '-r', '-z', 'HEAD', '--', 'qa'], timeoutMs);
+  if (r.ok) {
+    const blobs = new Map<string, string>();
+    for (const rec of r.out.split('\0')) { const m = rec.match(RECORD); if (m && KEEP(m[2])) blobs.set(m[2], m[1]); }
+    return { root, timeoutMs, blobs };
+  }
+  if (r.timedOut) return { root, timeoutMs, blobs: null, error: `git timed out after ${timeoutMs} ms` };
+  if (!hasDotGit(root)) return { root, timeoutMs, blobs: null };
+  const repo = runGit(root, ['rev-parse', '--git-dir'], timeoutMs);
+  if (repo.ok && !runGit(root, ['rev-parse', '--verify', '-q', 'HEAD'], timeoutMs).ok) return { root, timeoutMs, blobs: null };  // no first commit yet
+  return { root, timeoutMs, blobs: null, error: r.message || 'git failed' };
+}
+
+export const gitBlobId = (text: string): string => {
+  const body = Buffer.from(text, 'utf8');
+  return createHash('sha1').update(Buffer.concat([Buffer.from(`blob ${body.length}\0`), body])).digest('hex');
+};
+
+export const posixRel = (root: string, abs: string): string => path.relative(root, abs).split(path.sep).join('/');
+
+/**
+ * The committed text of a project-relative path, or null when HEAD does not hold it. `workingText`
+ * (the file as it is on disk, if any) spares the `git show` when it is byte-identical to HEAD.
+ */
+export function headFileText(snap: HeadSnapshot, rel: string, workingText: string | null): string | null {
+  const blob = snap.blobs?.get(rel);
+  if (blob === undefined) return null;
+  if (workingText !== null && gitBlobId(workingText) === blob) return workingText;
+  const r = runGit(snap.root, ['show', `HEAD:./${rel}`], snap.timeoutMs);
+  if (!r.ok) throw new GitUnavailableError(`git show HEAD:${rel}: ${r.timedOut ? 'timed out' : r.message}`);
+  return r.out;
+}
+
+/** A file's text, or null when it does not exist. */
+export function readTextOrNull(file: string): string | null {
+  try { return fs.readFileSync(file, 'utf8'); } catch (e) {
+    if ((e as NodeJS.ErrnoException).code === 'ENOENT') return null;
+    throw e;
+  }
+}

package/src/contract/contract-hash.ts

@@ -0,0 +1,34 @@
+/**
+ * Contract hash (DOS-14.2): `sha256-12` of the normalized steps PLUS the implementation path, so
+ * retagging `@free` → none is a contract change (red-team #5).
+ *
+ * Canonical JSON is keys-sorted with absent fields dropped and NO other rewriting: a literal's
+ * whitespace is part of what the test types or expects, so two values that differ only in spaces
+ * hash apart rather than "matching" by normalization.
+ */
+import { createHash } from 'crypto';
+import type { ContractStep, Implementation } from './contract-schema';
+
+function canonical(v: unknown): unknown {
+  if (Array.isArray(v)) return v.map(canonical);
+  if (v && typeof v === 'object') {
+    const out: Record<string, unknown> = {};
+    for (const k of Object.keys(v).sort()) {
+      const x = (v as Record<string, unknown>)[k];
+      if (x !== undefined) out[k] = canonical(x);
+    }
+    return out;
+  }
+  return v;
+}
+
+export const canonicalJson = (v: unknown): string => JSON.stringify(canonical(v));
+
+/** Structural equality, key order ignored. */
+export const sameJson = (a: unknown, b: unknown): boolean => canonicalJson(a) === canonicalJson(b);
+
+export const sha256Hex = (s: string): string => createHash('sha256').update(s).digest('hex');
+
+export function contractHash(implementation: Implementation, steps: ContractStep[]): string {
+  return sha256Hex(canonicalJson({ implementation, steps })).slice(0, 12);
+}

package/src/contract/contract-report-file.ts

@@ -0,0 +1,25 @@
+/**
+ * `.sungen/reports/<slug>-contract.json` — the contract verdict as OUTPUT (DOS-14.0, takumi T3).
+ *
+ * Written by `sungen contract check` from a verdict it just built; never read back as a source of
+ * truth. Anything that needs the verdict calls buildContractVerdict() and rebuilds it from the
+ * `.feature`, the lock and git HEAD — so editing this file to "pass" changes nothing, and the next
+ * check overwrites it. It records `inputsHash` so a reader can see the report is stale, and
+ * `exitCode` next to `verdict` (fail ⇔ exitCode ≠ 0).
+ */
+import * as fs from 'fs';
+import * as path from 'path';
+import { writeFileAtomic } from '../harness/write-atomic';
+import { reportSlug } from '../harness/unit-paths';
+import type { ContractVerdict } from './build-contract-verdict';
+
+export const contractReportPath = (projectRoot: string, unit: string): string =>
+  path.join(projectRoot, '.sungen', 'reports', `${reportSlug(unit)}-contract.json`);
+
+export function writeContractReport(projectRoot: string, verdict: ContractVerdict): string {
+  const file = contractReportPath(projectRoot, verdict.unit);
+  fs.mkdirSync(path.dirname(file), { recursive: true });
+  const doc = { ...verdict, generatedBy: 'sungen contract check', generatedAt: new Date().toISOString() };
+  writeFileAtomic(file, `${JSON.stringify(doc, null, 2)}\n`);
+  return file;
+}

package/src/contract/contract-schema.ts

@@ -0,0 +1,166 @@
+/**
+ * The Test Contract's data model (DOS-14.1 – 14.4) and the strict check of a stored lock entry.
+ *
+ *   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?, 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
+ * vouch for. `humanApproved` counts only when it is literally `true` (takumi T5).
+ */
+import { DECISION_ID_RE } from '../decisions/decision-schema';
+
+export const IMPLEMENTATIONS = ['compiled', 'impl:code', 'free'] as const;
+export type Implementation = typeof IMPLEMENTATIONS[number];
+
+export interface ContractTarget {
+  /** The first `[Reference]` of the step, or the data path of an `expect {{x}} …` step. */
+  ref: string;
+  /** Further `[References]` in the order written (`drag [A] to [B]`, `all [Card] contain [Child]`). */
+  also?: string[];
+  /** The `in [Parent] <container>` scope, as `<container> [<Parent>]` plus its `with` tail. */
+  parent?: string;
+  nth?: number;
+}
+
+export interface ContractStep {
+  kind: 'action' | 'assert';
+  /** The sentence with the actor dropped, refs as `[]`, values as `{}`, lowercased — the step's exact form. */
+  verb: string;
+  target?: ContractTarget;
+  /** An action's input: `{{var}}` kept as written, a literal without its quotes; several joined by ` | `. */
+  value?: string;
+  /** An assertion's check, from the closed vocabulary in oracle-strength.ts (`unknown` when it has none). */
+  matcher?: string;
+  /** An assertion's expected value(s), same form as `value`. */
+  expected?: string;
+  negated?: true;
+  /** The step's data table, header row first. */
+  table?: string[][];
+}
+
+export interface ContractScenario {
+  id: string;
+  implementation: Implementation;
+  steps: ContractStep[];
+  hash: string;
+  /** Where it was read — never hashed. `outline`: a Scenario Outline, which the compiler does not support. */
+  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[];
+  implementation: Implementation;
+  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> }
+
+export type LadderClass = 'match' | 'strengthened' | 'hash-changed' | 'oracle-weakened' | 'target-changed' | 'assertion-lost';
+/** Classes only a trace can produce (DOS-14.6) — free / impl:code scenarios. */
+export type TraceClass = 'opaque' | 'nondeterministic' | 'inconclusive' | 'unproven';
+export type ScenarioClass = LadderClass | 'proposed' | TraceClass;
+export type FindingClass = Exclude<LadderClass, 'match'> | 'lock-uncommitted' | TraceClass;
+
+/** Exit ≠ 0 (DOS-14.4, DOS-14.6). `unproven` applies to free / impl:code only. */
+export const HARD_CLASSES: ReadonlySet<string> = new Set(['oracle-weakened', 'target-changed', 'assertion-lost', 'lock-uncommitted', 'unproven']);
+/** Exit 0, but delivery waits for QA (DOS-14.4): changed-not-weaker, checks no code can compare, and an
+ *  approved free scenario whose final attempt did not pass (inconclusive — review decision M6). */
+export const REVIEW_CLASSES: ReadonlySet<string> = new Set(['hash-changed', 'opaque', 'inconclusive']);
+
+/** The catalog rule each class is reported under (gate-rules.yaml); `strengthened` has none. */
+export const RULE_OF: Readonly<Partial<Record<FindingClass, string>>> = {
+  'hash-changed': 'contract.hash-changed',
+  'oracle-weakened': 'contract.oracle-weakened',
+  'target-changed': 'contract.target-changed',
+  'assertion-lost': 'contract.assertion-lost',
+  'lock-uncommitted': 'contract.lock-uncommitted',
+  opaque: 'contract.opaque-step',
+  nondeterministic: 'contract.nondeterministic',
+  inconclusive: 'contract.inconclusive',
+  unproven: 'contract.unproven',
+};
+
+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', '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');
+const unknownKeys = (o: Record<string, unknown>, allowed: Set<string>, at: string): string[] =>
+  Object.keys(o).filter((k) => !allowed.has(k)).map((k) => `${at}: unknown key "${k}"`);
+
+function targetErrors(t: unknown, at: string): string[] {
+  if (!isObject(t)) return [`${at}: target must be a mapping`];
+  const e = unknownKeys(t, TARGET_KEYS, at);
+  if (typeof t.ref !== 'string') e.push(`${at}: target.ref must be a string`);
+  if (t.also !== undefined && !isStringList(t.also)) e.push(`${at}: target.also must be a list of strings`);
+  if (t.parent !== undefined && typeof t.parent !== 'string') e.push(`${at}: target.parent must be a string`);
+  if (t.nth !== undefined && !(Number.isInteger(t.nth) && (t.nth as number) > 0)) e.push(`${at}: target.nth must be a positive integer`);
+  return e;
+}
+
+export function stepErrors(s: unknown, at: string): string[] {
+  if (!isObject(s)) return [`${at}: not a mapping`];
+  const e = unknownKeys(s, STEP_KEYS, at);
+  if (s.kind !== 'action' && s.kind !== 'assert') e.push(`${at}: kind must be action|assert`);
+  if (typeof s.verb !== 'string' || !s.verb) e.push(`${at}: verb is required`);
+  if (s.target !== undefined) e.push(...targetErrors(s.target, at));
+  for (const k of ['value', 'matcher', 'expected'] as const) if (s[k] !== undefined && typeof s[k] !== 'string') e.push(`${at}: ${k} must be a string`);
+  if (s.negated !== undefined && s.negated !== true) e.push(`${at}: negated is either true or absent`);
+  if (s.table !== undefined && !(Array.isArray(s.table) && s.table.every(isStringList))) e.push(`${at}: table must be rows of strings`);
+  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}`;
+  if (!isObject(raw)) return [`${at}: not a mapping`];
+  const e = unknownKeys(raw, ENTRY_KEYS, at);
+  if (typeof raw.hash !== 'string' || !HASH_RE.test(raw.hash)) e.push(`${at}: hash must be 12 hex characters`);
+  if (!IMPLEMENTATIONS.includes(raw.implementation as Implementation)) e.push(`${at}: implementation must be ${IMPLEMENTATIONS.join('|')}`);
+  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;
+}
+
+/** Approved by a human on a TTY — and nothing else counts (an absent field is `proposed`, T5). */
+export const isHumanApproved = (entry: LockEntry | undefined): entry is LockEntry => entry?.humanApproved === true;

package/src/contract/contract-units.ts

@@ -0,0 +1,52 @@
+/**
+ * Which units a contract command or a `sungen delivery` call touches — the same units `delivery`
+ * enumerates (cli/commands/delivery.ts `listAllTargets` / `resolveTargetsFromArg`), restated here
+ * so the guard does not load the whole delivery command; a test pins the two enumerations together.
+ *
+ *   every unit       qa/screens/*, qa/flows/*, qa/api/* (not `flows`), and qa/api/flows/* as `flows/<name>`
+ *   a name           EVERY directory it can mean (a screen and a flow of one name are both checked);
+ *                    for delivery only, a name that is no unit falls back to the units hosting a
+ *                    feature file of that basename
+ *
+ * Names come from untrusted input (a Bash command): they are only compared with enumerated directory
+ * names, never joined into a path.
+ */
+import * as fs from 'fs';
+import * as path from 'path';
+import { featureFilesFor } from '../harness/unit-paths';
+
+export interface ContractUnitRef { name: string; dir: string }
+
+function subdirs(dir: string): string[] {
+  try { return fs.readdirSync(dir, { withFileTypes: true }).filter((e) => e.isDirectory()).map((e) => e.name).sort(); } catch { return []; }
+}
+
+export function allContractUnits(root: string): ContractUnitRef[] {
+  const qa = path.join(root, 'qa');
+  const out: ContractUnitRef[] = [];
+  for (const kind of ['screens', 'flows', 'api']) {
+    for (const name of subdirs(path.join(qa, kind))) if (!(kind === 'api' && name === 'flows')) out.push({ name, dir: path.join(qa, kind, name) });
+  }
+  for (const name of subdirs(path.join(qa, 'api', 'flows'))) out.push({ name: `flows/${name}`, dir: path.join(qa, 'api', 'flows', name) });
+  return out;
+}
+
+/** Every unit directory `name` can mean (`pay` matches a flow `pay` and an api flow `flows/pay`). */
+export function contractUnitDirsNamed(root: string, name: string): ContractUnitRef[] {
+  return allContractUnits(root).filter((u) => u.name === name || u.name === `flows/${name}`);
+}
+
+/** The units `sungen delivery <name>` delivers. */
+export function deliveryUnitsNamed(root: string, name: string): ContractUnitRef[] {
+  const direct = contractUnitDirsNamed(root, name);
+  if (direct.length) return direct;
+  return allContractUnits(root).filter((u) => featureFilesFor(u.dir, u.name).some((f) => path.basename(f, '.feature') === name && fs.existsSync(f)));
+}
+
+/** The one unit a contract command names; an unknown or ambiguous name is an error, never a guess. */
+export function resolveContractUnit(root: string, name: string): ContractUnitRef {
+  const found = contractUnitDirsNamed(root, name);
+  if (found.length === 1) return found[0];
+  if (!found.length) throw new Error(`Not found: qa/screens/${name}, qa/flows/${name}, qa/api/${name} or qa/api/flows/${name}`);
+  throw new Error(`"${name}" names ${found.length} units (${found.map((u) => path.relative(root, u.dir)).join(', ')}) — rename one so the contract knows which`);
+}