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

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

@@ -0,0 +1,68 @@
+/**
+ * A trace → its contract fingerprint: the rendered Gherkin steps normalized by the SAME parser and
+ * normalizer a hand-written `.feature` goes through (DOS-14.1), then hashed with the implementation
+ * path (DOS-14.2). So the fingerprint of a trace and the lock of the `.free.feature` derived from it
+ * are equal by construction — not by a second, parallel normalizer that could drift.
+ *
+ * The rendered steps are written to a throw-away `.feature` and read back with
+ * `scenariosOfFeatureFile`; nothing else in the pipeline parses Gherkin.
+ */
+import * as fs from 'fs';
+import * as os from 'os';
+import * as path from 'path';
+import { contractHash } from '../contract-hash';
+import type { ContractStep, Implementation } from '../contract-schema';
+import { scenariosOfFeatureFile } from '../normalize-feature-steps';
+import type { RenderedStep } from '../render-free-gherkin';
+
+const KEYWORD = /^(Given|When|Then|And|But)\s/;
+
+/** Normalize several step lists in one parse; `lines[i]` are full Gherkin lines (keyword first). */
+export function normalizeGherkinLines(blocks: string[][]): ContractStep[][] {
+  if (!blocks.length) return [];
+  const dir = fs.mkdtempSync(path.join(os.tmpdir(), 'sungen-fingerprint-'));
+  try {
+    const file = path.join(dir, 'fingerprint.feature');
+    const text = ['Feature: fingerprint', '', ...blocks.flatMap((lines, i) => [
+      `  Scenario: FP-${i + 1}0`, ...lines.map((l) => `    ${KEYWORD.test(l.trim()) ? l.trim() : `When ${l.trim()}`}`), '',
+    ])].join('\n');
+    fs.writeFileSync(file, text);
+    const parsed = scenariosOfFeatureFile(file);
+    if (parsed.length !== blocks.length) throw new Error(`fingerprint: ${blocks.length} step lists normalized to ${parsed.length} scenarios`);
+    return parsed.map((s) => s.steps);
+  } finally {
+    fs.rmSync(dir, { recursive: true, force: true });
+  }
+}
+
+export interface TraceFingerprint {
+  steps: ContractStep[];
+  hash: string;
+  rendered: RenderedStep[];
+  /** impl:code: each `test.step` title (normalized) and the indexes of the steps it holds. */
+  groups: Array<{ title: string; titleStep: ContractStep; members: number[] }>;
+}
+
+/** Many fingerprints from ONE temp-file parse (a unit's scenarios × runs) — the guard path's cost. */
+export function fingerprintsOf(items: Array<{ rendered: RenderedStep[]; implementation: Implementation }>): TraceFingerprint[] {
+  const blocks: string[][] = [];
+  const plan = items.map(({ rendered, implementation }) => {
+    const titles = implementation === 'impl:code' ? [...new Set(rendered.map((r) => r.group).filter((g): g is string => !!g))] : [];
+    const at = blocks.push(rendered.map((r) => `${r.keyword} ${r.sentence}`)) - 1;
+    const titlesAt = titles.length ? blocks.push(titles) - 1 : -1;
+    return { at, titlesAt, titles };
+  });
+  const normalized = normalizeGherkinLines(blocks);
+  return items.map(({ rendered, implementation }, i) => {
+    const { at, titlesAt, titles } = plan[i];
+    const steps = normalized[at];
+    const titleSteps = titlesAt >= 0 ? normalized[titlesAt] : [];
+    const groups = titles.map((title, k) => ({
+      title, titleStep: titleSteps[k], members: rendered.map((r, j) => (r.group === title ? j : -1)).filter((j) => j >= 0),
+    }));
+    return { steps, hash: contractHash(implementation, steps), rendered, groups };
+  });
+}
+
+export const fingerprintOf = (rendered: RenderedStep[], implementation: Implementation): TraceFingerprint =>
+  fingerprintsOf([{ rendered, implementation }])[0];

package/src/contract/trace/trace-identity-resolution.ts

@@ -0,0 +1,74 @@
+/**
+ * Every target of a trace → its identity (DOS-14.5): the driver's answer from the identity cache
+ * when one exists for the exact HTML core rendered, otherwise core's heuristic (always `low`).
+ *
+ * `resolveWithDriver` is the only asynchronous part of trace conformance: it renders the snapshots,
+ * asks the registered `traceIdentity` resolver (driver-ui: a real browser, JS off, every request
+ * blocked) for the ones not cached yet, and writes the cache. Everything else stays a plain
+ * function of the files on disk, so the CLI and the Claude Code guard build the same verdict.
+ */
+import { CachedIdentity, IdentityCache, readIdentityCache, writeIdentityCache } from './identity-cache';
+import { resolveCallTarget, CallTarget } from './snapshot-resolver';
+import { SnapshotStore } from './snapshot-store';
+import { heuristicIdentity, TraceIdentityRequest, TraceIdentityResolver, TRUSTED_RESOLVER, validIdentityResult } from './target-identity';
+import type { ParsedTrace } from './trace-file-reader';
+import { traceIntentSteps, IntentStep } from './trace-steps';
+import type { ResolvedTarget } from '../render-free-gherkin';
+
+const NO_DRIVER = 'no driver identity yet — run `sungen contract check --trace` (needs @sungen/driver-ui and a browser)';
+
+/** Steps aimed at the page itself carry no element identity. */
+export const isPageLevel = (s: IntentStep): boolean =>
+  s.method === 'goto' || /^keyboard/.test(s.method) || /^to\.have\.(url|title)$/.test(String(s.params.expression ?? '')) || s.kind.startsWith('opaque');
+
+function targetCalls(trace: ParsedTrace, steps: IntentStep[]): Array<{ callId: string; target: CallTarget | null }> {
+  const store = new SnapshotStore(trace.library);
+  return steps.filter((s) => s.callId && !isPageLevel(s)).map((s) => ({ callId: s.callId!, target: resolveCallTarget(store, trace, s.callId!) }));
+}
+
+export function identitiesFor(trace: ParsedTrace, steps: IntentStep[], cache: IdentityCache): Map<string, ResolvedTarget> {
+  const out = new Map<string, ResolvedTarget>();
+  for (const { callId, target } of targetCalls(trace, steps)) {
+    if (!target) { out.set(callId, { identity: heuristicIdentity(null, 'no snapshot marks this target') }); continue; }
+    const hit = cache.entries.get(target.snapshotSha256);
+    if (!hit) { out.set(callId, { identity: heuristicIdentity(target.facts, NO_DRIVER), facts: target.facts }); continue; }
+    // What core already knows (missing CSS, broken refs) caps the driver's answer, whatever it says.
+    const reasons = [...target.capReasons, ...hit.reasons];
+    out.set(callId, {
+      identity: { ...hit, identityConfidence: reasons.length ? 'low' : hit.identityConfidence, reasons, source: 'driver' },
+      facts: target.facts,
+    });
+  }
+  return out;
+}
+
+/** One replay request per element target of a trace, keyed by the sha256 of its rendered HTML. */
+export function identityRequestsFor(trace: ParsedTrace): TraceIdentityRequest[] {
+  return targetCalls(trace, traceIntentSteps(trace)).filter((t) => t.target).map(({ callId, target }) => ({
+    key: target!.snapshotSha256, html: target!.html, viewport: target!.viewport,
+    targetSelector: `[__playwright_target__="${callId}"]`, capReasons: target!.capReasons,
+  }));
+}
+
+/** Ask the driver about every not-yet-cached target of these traces; rewrite the cache. */
+export async function resolveWithDriver(projectRoot: string, traces: ParsedTrace[], resolver: TraceIdentityResolver): Promise<{ asked: number; resolver: string; blockedRequests: number }> {
+  const { cache } = readIdentityCache(projectRoot);
+  // The cache is project-wide (every unit's traces): answers are only ever ADDED, never pruned here.
+  const keep = new Map<string, CachedIdentity>(cache.entries);
+  const requests = new Map<string, TraceIdentityRequest>();
+  for (const req of traces.flatMap(identityRequestsFor)) if (!keep.has(req.key)) requests.set(req.key, req);
+  if (!requests.size) return { asked: 0, resolver: cache.resolver, blockedRequests: 0 };
+  const answer = await resolver({ requests: [...requests.values()] });
+  if (!answer || !Array.isArray(answer.results)) throw new Error('the trace identity resolver returned no results');
+  if (!TRUSTED_RESOLVER.test(String(answer.resolver)) || typeof answer.browser !== 'string' || !answer.browser) {
+    throw new Error(`the trace identity resolver "${String(answer.resolver).slice(0, 40)}" is not driver-ui's, or named no browser — its answers are not kept`);
+  }
+  for (const raw of answer.results) {
+    const r = validIdentityResult(raw);
+    if (!r || !requests.has(r.key)) throw new Error(`the trace identity resolver returned a malformed or unasked-for result (${JSON.stringify(raw).slice(0, 120)})`);
+    const { key, ...rest } = r;
+    keep.set(key, { ...rest, browser: answer.browser.slice(0, 100) });
+  }
+  writeIdentityCache(projectRoot, answer.resolver, keep);
+  return { asked: requests.size, resolver: String(answer.resolver), blockedRequests: Number(answer.blockedRequests) || 0 };
+}

package/src/contract/trace/trace-run-record.ts

@@ -0,0 +1,80 @@
+/**
+ * sungen's own run record (G5, DOS-14.6): written by `@sungen/driver-ui`'s run-record reporter
+ * next to the traces, read here STRICTLY — it is the only place a trace's run id and the hash of
+ * the code that produced it live, so an unknown key, a wrong type or a malformed hash means the
+ * record is not trusted at all (every trace it would vouch for is unbound).
+ *
+ * Found by convention: `<project>/test-results-free/sungen-run-record*.json` — the free-test config's
+ * own outputDir (#941) — or `<project>/test-results/sungen-run-record*.json` (one per run or shard).
+ * Playwright wipes its outputDir at the start of every run, so a record and its traces share a
+ * lifetime; the free run has its own so the compiled suite's next run cannot delete its traces.
+ */
+import * as fs from 'fs';
+import * as path from 'path';
+
+export interface RunRecordAttempt {
+  testId: string; file: string; title: string; retry: number; status: string;
+  startTime: string; duration: number; trace: { sha256: string } | null;
+}
+export interface RunRecord {
+  file: string;
+  runId: string;
+  startedAt: string;
+  playwrightVersion: string;
+  shard: string | null;
+  report: string | null;
+  specs: Record<string, string>;
+  attempts: RunRecordAttempt[];
+}
+
+const TOP = new Set(['schema', 'tool', 'runId', 'startedAt', 'playwrightVersion', 'shard', 'report', 'specs', 'attempts']);
+const ATTEMPT = new Set(['testId', 'file', 'title', 'retry', 'status', 'startTime', 'duration', 'trace']);
+const SHA = /^[0-9a-f]{64}$/;
+const isObj = (v: unknown): v is Record<string, unknown> => !!v && typeof v === 'object' && !Array.isArray(v);
+
+/** The free / impl:code run's own outputDir (the documented free-test config); compiled runs clear `test-results/`. */
+export const FREE_RUN_DIR = 'test-results-free';
+/** Where run records are read, in this order: the free run's dir, then Playwright's default (older configs). */
+export const RUN_RECORD_DIRS: readonly string[] = [FREE_RUN_DIR, 'test-results'];
+
+export function findRunRecords(projectRoot: string): string[] {
+  return RUN_RECORD_DIRS.flatMap((rel) => {
+    const dir = path.join(projectRoot, rel);
+    let names: string[];
+    try { names = fs.readdirSync(dir); } catch { return []; }
+    return names.filter((n) => /^sungen-run-record(?:\.[A-Za-z0-9._-]+)?\.json$/.test(n)).sort().map((n) => path.join(dir, n));
+  });
+}
+
+function attemptOf(raw: unknown, i: number): RunRecordAttempt {
+  const at = `attempt ${i + 1}`;
+  if (!isObj(raw)) throw new Error(`${at} is not an object`);
+  const extra = Object.keys(raw).find((k) => !ATTEMPT.has(k));
+  if (extra) throw new Error(`${at} has an unknown key "${extra}"`);
+  const { testId, file, title, retry, status, startTime, duration, trace } = raw;
+  if (typeof testId !== 'string' || typeof file !== 'string' || typeof title !== 'string' || typeof status !== 'string') throw new Error(`${at}: testId, file, title and status must be strings`);
+  if (!Number.isInteger(retry) || (retry as number) < 0 || typeof duration !== 'number' || typeof startTime !== 'string' || Number.isNaN(Date.parse(startTime))) {
+    throw new Error(`${at}: retry, duration and startTime are malformed`);
+  }
+  if (trace !== null && !(isObj(trace) && Object.keys(trace).length === 1 && typeof trace.sha256 === 'string' && SHA.test(trace.sha256))) throw new Error(`${at}: trace must be null or {sha256}`);
+  return { testId, file, title, retry: retry as number, status, startTime, duration, trace: trace as RunRecordAttempt['trace'] };
+}
+
+/** Read and check one record; throws an Error naming what is wrong. */
+export function readRunRecord(file: string): RunRecord {
+  let raw: unknown;
+  try { raw = JSON.parse(fs.readFileSync(file, 'utf8')); } catch (e) { throw new Error(`not readable JSON (${(e as Error).message.split('\n')[0]})`); }
+  if (!isObj(raw)) throw new Error('not an object');
+  const extra = Object.keys(raw).find((k) => !TOP.has(k));
+  if (extra) throw new Error(`unknown key "${extra}"`);
+  if (raw.schema !== 1 || raw.tool !== 'sungen-trace-run-record') throw new Error('not a sungen run record (schema 1)');
+  if (typeof raw.runId !== 'string' || !raw.runId || typeof raw.startedAt !== 'string' || typeof raw.playwrightVersion !== 'string') throw new Error('runId, startedAt and playwrightVersion must be strings');
+  if (raw.shard !== null && typeof raw.shard !== 'string') throw new Error('shard must be a string or null');
+  if (raw.report !== null && typeof raw.report !== 'string') throw new Error('report must be a string or null');
+  if (!isObj(raw.specs) || !Object.values(raw.specs).every((v) => typeof v === 'string' && (v === '' || SHA.test(v)))) throw new Error('specs must map files to sha256');
+  if (!Array.isArray(raw.attempts)) throw new Error('attempts must be a list');
+  return {
+    file, runId: raw.runId, startedAt: raw.startedAt, playwrightVersion: raw.playwrightVersion, shard: raw.shard as string | null,
+    report: raw.report as string | null, specs: raw.specs as Record<string, string>, attempts: raw.attempts.map(attemptOf),
+  };
+}

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

@@ -0,0 +1,88 @@
+/**
+ * A trace → the test's INTENT, in order (phase 08 requirement 1). What is kept:
+ *
+ *   action         Frame goto / click / dblclick / fill / check / uncheck / selectOption / press /
+ *                  hover / setInputFiles / type / tap, and page keyboard presses
+ *   assert         Frame.expect — a check on an element or the page (url, title)
+ *   opaque-assert  a runner `expect` with no browser call behind it: `expect(await res.json())…`,
+ *                  a check on a JS value — cannot be compared, always review (DOS-14.6)
+ *   opaque-action  an API request, an `evaluate` (canvas…) — behaviour the contract cannot see into
+ *
+ * Dropped as implementation detail: waits (`waitForTimeout`, `waitFor*`), reads (`textContent`,
+ * `isVisible`…), context/page plumbing, and everything in fixtures, runner hooks and teardown —
+ * only the body and user `beforeEach` hooks are the test's behaviour. A focus click right before a
+ * fill on the same element is dropped later, once identities say "same element" (render step).
+ */
+import { classifyStep, isBehaviour, joinCalls, RunnerStep } from './test-step-join';
+import type { ParsedTrace, StackFrame } from './trace-file-reader';
+
+export type IntentKind = 'action' | 'assert' | 'opaque-action' | 'opaque-assert';
+export interface IntentStep {
+  kind: IntentKind;
+  method: string;
+  callId?: string;
+  params: Record<string, unknown>;
+  /** Enclosing `test.step` titles, outermost first (impl:code compares by the first). */
+  group: string[];
+  location?: { file: string; line: number };
+  /** The runner's own words for an opaque step (`Expect "toMatchObject"`, `GET /api/health`). */
+  verbatim?: string;
+  startTime: number;
+}
+
+const FRAME_ACTIONS = new Set(['goto', 'click', 'dblclick', 'fill', 'check', 'uncheck', 'selectOption', 'press', 'hover', 'setInputFiles', 'type', 'tap']);
+const PAGE_KEYS = new Set(['keyboardPress', 'keyboardType', 'keyboardInsertText']);
+const EVALUATE = /^evaluate/;
+
+/** The first frame in the test's own code (not a library, not the runner's `project#` marker). */
+function firstFrame(frames: StackFrame[] | undefined): { file: string; line: number } | undefined {
+  const f = frames?.find((x) => x.file && !x.file.includes('node_modules') && !x.file.endsWith('#'));
+  return f ? { file: f.file, line: f.line } : undefined;
+}
+
+function groupOf(steps: Map<string, RunnerStep>, stepId: string | undefined): string[] {
+  if (!stepId) return [];
+  const w = classifyStep(steps, stepId);
+  return w.phase === 'body' ? w.stepPath : [];
+}
+
+export function traceIntentSteps(trace: ParsedTrace): IntentStep[] {
+  const { steps, calls } = joinCalls(trace);
+  const stacks = new Map(trace.library.map((l) => [l.name, l.stacks]));
+  const out: IntentStep[] = [];
+  const withCall = new Set(calls.map((c) => c.stepId).filter((s): s is string => !!s));
+
+  for (const c of calls) {
+    if (!isBehaviour(c.where)) continue;
+    let kind: IntentKind | null = null;
+    let verbatim: string | undefined;
+    if (c.class === 'Frame' && FRAME_ACTIONS.has(c.method)) kind = 'action';
+    else if (c.class === 'Frame' && c.method === 'expect') kind = 'assert';
+    else if (c.class === 'Page' && PAGE_KEYS.has(c.method)) kind = 'action';
+    else if (c.class === 'APIRequestContext' && c.method === 'fetch') {
+      kind = 'opaque-action';
+      verbatim = `${String(c.params.method ?? 'GET')} ${String(c.params.url ?? '')}`;
+    } else if (EVALUATE.test(c.method) && /^(Frame|Page|JSHandle|ElementHandle|Worker)$/.test(c.class)) {
+      kind = 'opaque-action';
+      verbatim = `${c.class}.${c.method}`;
+    }
+    if (!kind) continue;
+    const runner = c.stepId ? steps.get(c.stepId) : undefined;
+    out.push({
+      kind, method: c.method, callId: c.callId, params: c.params, group: groupOf(steps, c.stepId),
+      location: firstFrame(runner?.stack) ?? firstFrame(stacks.get(c.part)?.get(c.callId)),
+      ...(verbatim ? { verbatim } : {}), startTime: c.startTime,
+    });
+  }
+
+  // A runner `expect` that drove no browser call checked a plain JS value: opaque.
+  const runnerStart = new Map(trace.runner.filter((e) => e.type === 'before').map((e) => [String(e.callId), Number(e.startTime) || 0]));
+  for (const s of steps.values()) {
+    if (s.method !== 'expect' || withCall.has(s.id) || !isBehaviour(classifyStep(steps, s.id))) continue;
+    out.push({
+      kind: 'opaque-assert', method: 'expect', params: s.params, group: groupOf(steps, s.id),
+      location: firstFrame(s.stack), verbatim: s.title, startTime: runnerStart.get(s.id) ?? 0,
+    });
+  }
+  return out.sort((a, b) => a.startTime - b.startTime);
+}

package/src/contract/trace/trace-zip-limits.ts

@@ -0,0 +1,77 @@
+/**
+ * Limits for reading an untrusted Playwright trace.zip (DOS-14.7), and the one error every trace
+ * refusal raises. A trace is attacker-shaped input: a report can point at any file, and a zip can
+ * claim small sizes and inflate to gigabytes, so every number below is checked BEFORE inflating and
+ * again WHILE inflating (the inflater is capped at the declared size).
+ *
+ *   file size           20 MB        a real trace is ~0.6 MB per attempt, max 1.3 MB measured (phase 07)
+ *   entries            10 000
+ *   one entry           16 MB uncompressed
+ *   all entries         64 MB uncompressed   (each raisable by env: traceZipLimits)
+ *   ratio              100 : 1 per entry (a bomb is ~1000 : 1)
+ *
+ * An entry NAME is a key and nothing else: names with `..`, a leading `/`, a drive letter, a
+ * backslash or a NUL are refused outright rather than "sanitized", because nothing legitimate in a
+ * trace looks like that.
+ */
+export interface TraceZipLimits {
+  maxZipBytes: number;
+  maxEntries: number;
+  maxEntryBytes: number;
+  maxTotalBytes: number;
+  maxRatio: number;
+}
+
+const MB = 1024 * 1024;
+
+export const TRACE_ZIP_LIMITS: Readonly<TraceZipLimits> = Object.freeze({
+  maxZipBytes: 20 * MB,
+  maxEntries: 10_000,
+  maxEntryBytes: 16 * MB,
+  maxTotalBytes: 64 * MB,
+  maxRatio: 100,
+});
+
+/**
+ * The limits in force: the defaults, each raisable by env for unusually large traces —
+ * `SUNGEN_TRACE_MAX_ZIP_MB`, `SUNGEN_TRACE_MAX_ENTRY_MB`, `SUNGEN_TRACE_MAX_TOTAL_MB` (positive numbers;
+ * anything else is ignored, so a typo can never turn a cap into zero or infinity).
+ */
+export function traceZipLimits(env: Record<string, string | undefined> = process.env): TraceZipLimits {
+  const mb = (name: string, fallback: number): number => {
+    const v = Number(env[name]);
+    return Number.isFinite(v) && v > 0 && v <= 4096 ? Math.floor(v * MB) : fallback;
+  };
+  return {
+    ...TRACE_ZIP_LIMITS,
+    maxZipBytes: mb('SUNGEN_TRACE_MAX_ZIP_MB', TRACE_ZIP_LIMITS.maxZipBytes),
+    maxEntryBytes: mb('SUNGEN_TRACE_MAX_ENTRY_MB', TRACE_ZIP_LIMITS.maxEntryBytes),
+    maxTotalBytes: mb('SUNGEN_TRACE_MAX_TOTAL_MB', TRACE_ZIP_LIMITS.maxTotalBytes),
+  };
+}
+
+/**
+ * Trace format versions this reader was verified against: 8 = Playwright 1.57, 9 = 1.63, 10 = 1.64
+ * (one shared call id for a library call and its runner step; stacks keyed by that id). Anything
+ * else — a newer format included — is refused until it has been checked the same way.
+ */
+export const SUPPORTED_TRACE_VERSIONS: ReadonlySet<number> = new Set([8, 9, 10]);
+
+export type TraceRejectCode =
+  | 'zip.too-large' | 'zip.too-many-entries' | 'zip.entry-too-large' | 'zip.total-too-large' | 'zip.ratio'
+  | 'zip.entry-name' | 'zip.malformed' | 'zip.unsupported' | 'trace.version-unsupported' | 'trace.malformed';
+
+/** A trace that was refused before anything in it was trusted. `code` is stable; `message` names the cause. */
+export class TraceRejected extends Error {
+  constructor(public readonly code: TraceRejectCode, message: string) {
+    super(`${code}: ${message}`);
+    this.name = 'TraceRejected';
+  }
+}
+
+const BAD_NAME = /(^|[\\/])\.\.([\\/]|$)|^[\\/]|^[A-Za-z]:|\\|\0/;
+
+/** Refuse an entry name that could ever be mistaken for a path outside the archive. */
+export function assertSafeEntryName(name: string): void {
+  if (!name || BAD_NAME.test(name)) throw new TraceRejected('zip.entry-name', `refused entry name ${JSON.stringify(name.slice(0, 80))}`);
+}

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

@@ -0,0 +1,127 @@
+/**
+ * A synchronous, limit-enforcing zip reader for trace.zip files (DOS-14.7) on Node's own zlib —
+ * no dependency, and synchronous so the contract verdict (and the Claude Code guard that rebuilds
+ * it) stays a plain function.
+ *
+ * Only what a Playwright trace needs is accepted: STORE or DEFLATE entries, no encryption, no
+ * ZIP64, no duplicate names. Sizes come from the central directory and are checked against
+ * TRACE_ZIP_LIMITS before anything is inflated; inflation itself is capped at the declared size and
+ * the CRC is verified, so a header that lies is caught while reading, not after. Entry names are
+ * map keys — nothing here ever touches the filesystem.
+ */
+import * as zlib from 'zlib';
+import { assertSafeEntryName, TRACE_ZIP_LIMITS, TraceRejected, TraceZipLimits } from './trace-zip-limits';
+
+interface Entry { name: string; method: number; compressed: number; size: number; crc: number; localOffset: number }
+
+export interface ZipArchive {
+  names(): string[];
+  has(name: string): boolean;
+  readBuffer(name: string): Buffer;
+  readText(name: string): string;
+}
+
+const EOCD = 0x06054b50;
+const CENTRAL = 0x02014b50;
+const LOCAL = 0x04034b50;
+/** Below this, a high ratio is just a small repetitive file; the per-entry and total caps still apply. */
+const RATIO_FLOOR_BYTES = 64 * 1024;
+
+const malformed = (why: string): TraceRejected => new TraceRejected('zip.malformed', why);
+
+const CRC_TABLE = (() => {
+  const t = new Int32Array(256);
+  for (let n = 0; n < 256; n++) { let c = n; for (let k = 0; k < 8; k++) c = c & 1 ? 0xedb88320 ^ (c >>> 1) : c >>> 1; t[n] = c; }
+  return t;
+})();
+function crc32(buf: Buffer): number {
+  let c = -1;
+  for (let i = 0; i < buf.length; i++) c = CRC_TABLE[(c ^ buf[i]) & 0xff] ^ (c >>> 8);
+  return (c ^ -1) >>> 0;
+}
+
+function findEocd(buf: Buffer): number {
+  const stop = Math.max(0, buf.length - 22 - 0xffff);
+  for (let i = buf.length - 22; i >= stop; i--) if (buf.readUInt32LE(i) === EOCD) return i;
+  throw malformed('no end-of-central-directory record (not a zip)');
+}
+
+function readEntries(buf: Buffer, limits: TraceZipLimits): Map<string, Entry> {
+  const eocd = findEocd(buf);
+  const count = buf.readUInt16LE(eocd + 10);
+  const cdOffset = buf.readUInt32LE(eocd + 16);
+  if (count === 0xffff || cdOffset === 0xffffffff) throw new TraceRejected('zip.unsupported', 'ZIP64 archives are not read');
+  if (count > limits.maxEntries) throw new TraceRejected('zip.too-many-entries', `${count} entries > ${limits.maxEntries}`);
+  const entries = new Map<string, Entry>();
+  let at = cdOffset;
+  let total = 0;
+  for (let i = 0; i < count; i++) {
+    if (buf.readUInt32LE(at) !== CENTRAL) throw malformed(`central directory entry ${i} has a bad signature`);
+    const flags = buf.readUInt16LE(at + 8);
+    const method = buf.readUInt16LE(at + 10);
+    const crc = buf.readUInt32LE(at + 16);
+    const compressed = buf.readUInt32LE(at + 20);
+    const size = buf.readUInt32LE(at + 24);
+    const nameLen = buf.readUInt16LE(at + 28);
+    const name = buf.toString('utf8', at + 46, at + 46 + nameLen);
+    const localOffset = buf.readUInt32LE(at + 42);
+    at += 46 + nameLen + buf.readUInt16LE(at + 30) + buf.readUInt16LE(at + 32);
+    assertSafeEntryName(name.replace(/\/$/, '') || name);
+    if (flags & 1) throw new TraceRejected('zip.unsupported', `${name} is encrypted`);
+    if (method !== 0 && method !== 8) throw new TraceRejected('zip.unsupported', `${name} uses compression method ${method}`);
+    if (compressed === 0xffffffff || size === 0xffffffff) throw new TraceRejected('zip.unsupported', `${name} needs ZIP64`);
+    if (name.endsWith('/')) continue;
+    if (entries.has(name)) throw malformed(`duplicate entry ${name}`);
+    if (size > limits.maxEntryBytes) throw new TraceRejected('zip.entry-too-large', `${name}: ${size} B > ${limits.maxEntryBytes}`);
+    if (size >= RATIO_FLOOR_BYTES && compressed > 0 && size / compressed > limits.maxRatio) {
+      throw new TraceRejected('zip.ratio', `${name}: ratio ${(size / compressed).toFixed(0)}:1 > ${limits.maxRatio}:1`);
+    }
+    if (size >= RATIO_FLOOR_BYTES && compressed === 0) throw new TraceRejected('zip.ratio', `${name}: ${size} B from 0 compressed bytes`);
+    total += size;
+    if (total > limits.maxTotalBytes) throw new TraceRejected('zip.total-too-large', `more than ${limits.maxTotalBytes} B uncompressed`);
+    entries.set(name, { name, method, compressed, size, crc, localOffset });
+  }
+  return entries;
+}
+
+function inflate(buf: Buffer, e: Entry): Buffer {
+  if (buf.readUInt32LE(e.localOffset) !== LOCAL) throw malformed(`${e.name}: bad local header`);
+  const start = e.localOffset + 30 + buf.readUInt16LE(e.localOffset + 26) + buf.readUInt16LE(e.localOffset + 28);
+  const data = buf.subarray(start, start + e.compressed);
+  if (data.length !== e.compressed) throw malformed(`${e.name}: truncated data`);
+  let out: Buffer;
+  if (e.method === 0) out = data;
+  else {
+    try { out = zlib.inflateRawSync(data, { maxOutputLength: Math.max(1, e.size) }); } catch (err) {
+      throw malformed(`${e.name}: inflates past its declared ${e.size} B or is corrupt (${(err as Error).message.split('\n')[0]})`);
+    }
+  }
+  if (out.length !== e.size) throw malformed(`${e.name}: ${out.length} B, header says ${e.size} B`);
+  if (crc32(out) !== e.crc) throw malformed(`${e.name}: CRC mismatch`);
+  return out;
+}
+
+/** Open a zip held in memory. Throws TraceRejected for anything outside the limits or the format. */
+export function openZip(buf: Buffer, limits: TraceZipLimits = TRACE_ZIP_LIMITS): ZipArchive {
+  if (buf.length > limits.maxZipBytes) throw new TraceRejected('zip.too-large', `${buf.length} B > ${limits.maxZipBytes}`);
+  if (buf.length < 22) throw malformed('too short to be a zip');
+  let entries: Map<string, Entry>;
+  try { entries = readEntries(buf, limits); } catch (e) {
+    if (e instanceof TraceRejected) throw e;
+    throw malformed(`unreadable zip structure (${(e as Error).message.split('\n')[0]})`);
+  }
+  const readBuffer = (name: string): Buffer => {
+    const e = entries.get(name);
+    if (!e) throw malformed(`no entry ${name}`);
+    try { return inflate(buf, e); } catch (err) {
+      if (err instanceof TraceRejected) throw err;
+      throw malformed(`${name}: ${(err as Error).message.split('\n')[0]}`);
+    }
+  };
+  return {
+    names: () => [...entries.keys()],
+    has: (name) => entries.has(name),
+    readBuffer,
+    readText: (name) => readBuffer(name).toString('utf8'),
+  };
+}

package/src/contract/verify-approval-decisions.ts

@@ -0,0 +1,60 @@
+/**
+ * Every approved lock entry must be vouched for by its decision (DOS-13.2, DOS-14.4, review M1):
+ * `qa/<kind>/<unit>/decisions/<decisionId>.yaml`, COMMITTED in git HEAD (outside git: on disk),
+ * intact (schema, id = content, entry_hash = entry), of kind `contract-approval`, whose payload lists
+ * this scenario at this hash, and whose `valid_from` is the entry's `approvedAt`. A lock line copied
+ * from elsewhere, re-pointed at another decision, or backdated fails here — `unverified`, reported
+ * under contract.lock-uncommitted (hard).
+ *
+ * Only entries that are otherwise identical to HEAD are checked: an entry already added, changed or
+ * tampered is a hard finding on its own.
+ */
+import * as path from 'path';
+import { computeDecisionId, computeEntryHash } from '../decisions/decision-identity';
+import { DecisionEntry, storedEntryErrors } from '../decisions/decision-schema';
+import { safeYamlParse } from '../utils/safe-yaml-parse';
+import { HeadSnapshot, headFileText, posixRel, readTextOrNull } from './contract-git';
+import { ContractLock, isHumanApproved, LockEntry } from './contract-schema';
+import type { UncommittedEntry } from './lock-vs-git-head';
+
+type Loaded = { entry: DecisionEntry } | { problem: string };
+
+function loadDecision(projectRoot: string, unitDir: string, id: string, snap: HeadSnapshot): Loaded {
+  const file = path.join(unitDir, 'decisions', `${id}.yaml`);
+  const rel = posixRel(projectRoot, file);
+  const working = readTextOrNull(file);
+  const text = snap.blobs === null ? working : headFileText(snap, rel, working);
+  if (text === null) return { problem: snap.blobs === null ? `decision ${id} does not exist` : `decision ${id} is not in git HEAD (not committed through review)` };
+  let raw: unknown;
+  try { raw = safeYamlParse(text, rel); } catch (e) { return { problem: `decision ${id} is unreadable: ${e instanceof Error ? e.message : e}` }; }
+  const errors = storedEntryErrors(raw);
+  if (errors.length) return { problem: `decision ${id} is invalid: ${errors[0]}` };
+  const entry = raw as DecisionEntry;
+  const scope = posixRel(path.join(projectRoot, 'qa'), unitDir);
+  if (entry.id !== id || computeDecisionId(entry, scope) !== id) return { problem: `decision ${id} does not hash to its id in ${scope}` };
+  if (computeEntryHash(entry) !== entry.entry_hash) return { problem: `decision ${id} was altered (entry_hash)` };
+  return { entry };
+}
+
+function mismatch(scenario: string, lockEntry: LockEntry, d: DecisionEntry): string | null {
+  if (d.kind !== 'contract-approval') return `decision ${d.id} is a ${d.kind}, not a contract-approval`;
+  const listed = Array.isArray(d.payload?.scenarios) ? d.payload!.scenarios as Array<{ id?: unknown; hash?: unknown }> : [];
+  if (!listed.some((s) => s && s.id === scenario && s.hash === lockEntry.hash)) return `decision ${d.id} does not approve ${scenario} at hash ${lockEntry.hash}`;
+  if (Date.parse(lockEntry.approvedAt) !== Date.parse(d.valid_from)) return `approvedAt ${lockEntry.approvedAt} is not decision ${d.id}'s valid_from ${d.valid_from}`;
+  return null;
+}
+
+export function unverifiedApprovals(
+  projectRoot: string, unitDir: string, lock: ContractLock | null, skip: ReadonlySet<string>, snap: HeadSnapshot,
+): UncommittedEntry[] {
+  const cache = new Map<string, Loaded>();
+  const out: UncommittedEntry[] = [];
+  for (const [id, entry] of Object.entries(lock?.scenarios ?? {})) {
+    if (!isHumanApproved(entry) || skip.has(id)) continue;
+    if (!cache.has(entry.decisionId)) cache.set(entry.decisionId, loadDecision(projectRoot, unitDir, entry.decisionId, snap));
+    const loaded = cache.get(entry.decisionId)!;
+    const problem = 'problem' in loaded ? loaded.problem : mismatch(id, entry, loaded.entry);
+    if (problem) out.push({ id, change: 'unverified', detail: problem });
+  }
+  return out;
+}

package/src/decisions/append-decision.ts

@@ -0,0 +1,35 @@
+/**
+ * Append one decision: one file per entry, named by its content id, created exclusively
+ * (DOS-13.1, red-team #13). The file appears complete or not at all (createFileExclusive), so two
+ * writers can race freely: same content → same name → the second sees "already recorded"; different
+ * content → different names → both land. Nothing is sequential, so nothing can collide.
+ */
+import * as fs from 'fs';
+import * as path from 'path';
+import { createFileExclusive } from './exclusive-file-create';
+import { DecisionDraft, DecisionEntry, draftErrors } from './decision-schema';
+import { sealDecision } from './decision-identity';
+import { decisionsDirFor, serializeDecision, verifyDecisionFile } from './decision-file';
+
+export interface AppendResult { status: 'created' | 'already-recorded'; entry: DecisionEntry; path: string }
+
+export class DecisionConflictError extends Error {
+  constructor(public readonly path: string, detail: string) {
+    super(`${path} already exists but does not verify (${detail}). Restore it from git; record a new entry instead.`);
+    this.name = 'DecisionConflictError';
+  }
+}
+
+export function appendDecision(projectRoot: string, scope: string, draft: DecisionDraft): AppendResult {
+  const errors = draftErrors(draft as unknown as Record<string, unknown>);
+  if (errors.length) throw new Error(`invalid decision: ${errors.join('; ')}`);
+  const dir = decisionsDirFor(projectRoot, scope);
+  const entry = sealDecision(draft, scope);
+  fs.mkdirSync(dir, { recursive: true });
+  const file = path.join(dir, `${entry.id}.yaml`);
+  if (createFileExclusive(file, serializeDecision(entry))) return { status: 'created', entry, path: file };
+
+  const existing = verifyDecisionFile(file, scope);
+  if (existing.entry) return { status: 'already-recorded', entry: existing.entry, path: file };
+  throw new DecisionConflictError(file, `${existing.problem?.code}: ${existing.problem?.message}`);
+}