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

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) {

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

@@ -12,7 +12,7 @@
  * a part without one is refused. Every JSONL line must parse — a line that does not is never skipped.
  */
 import { createHash } from 'crypto';
-import * as fs from 'fs';
+import { FileRead, readFileOnce } from './read-file-once';
 import { openZip, ZipArchive } from './trace-zip-reader';
 import { SUPPORTED_TRACE_VERSIONS, traceZipLimits, TraceRejected, TraceZipLimits } from './trace-zip-limits';
 
@@ -124,10 +124,21 @@ export function readTraceBuffer(buf: Buffer, label: string, limits: TraceZipLimi
   };
 }
 
-/** Read a trace from disk: a regular file, size-checked BEFORE it is read into memory. */
+/**
+ * A trace opened once (read-file-once.ts) → parsed: the size was checked on the descriptor BEFORE it
+ * was read into memory. `missing` / `outside` are the caller's to report; here they throw.
+ */
+export function traceFromRead(read: FileRead, label: string, limits: TraceZipLimits = traceZipLimits()): ParsedTrace {
+  switch (read.status) {
+    case 'read': return readTraceBuffer(read.bytes, read.real, limits);
+    case 'too-large': throw new TraceRejected('zip.too-large', `${read.size} B > ${limits.maxZipBytes}`);
+    case 'not-a-file': throw new TraceRejected('zip.malformed', `${label} is not a regular file`);
+    case 'missing': throw new TraceRejected('zip.malformed', `${label} does not exist`);
+    default: throw new TraceRejected('zip.malformed', `${label} was not read: ${read.why}`);
+  }
+}
+
+/** Read a trace from a trusted path (a fixture, a test): a regular file, opened once. */
 export function readTraceFile(file: string, limits: TraceZipLimits = traceZipLimits()): ParsedTrace {
-  const st = fs.statSync(file);
-  if (!st.isFile()) throw new TraceRejected('zip.malformed', `${file} is not a regular file`);
-  if (st.size > limits.maxZipBytes) throw new TraceRejected('zip.too-large', `${st.size} B > ${limits.maxZipBytes}`);
-  return readTraceBuffer(fs.readFileSync(file), file, limits);
+  return traceFromRead(readFileOnce(file, limits.maxZipBytes), file, limits);
 }

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

@@ -60,10 +60,10 @@ function attemptOf(raw: unknown, i: number): RunRecordAttempt {
   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 {
+/** Read and check one record (`text`: its bytes, already read once by the caller); throws an Error naming what is wrong. */
+export function readRunRecord(file: string, text?: 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]})`); }
+  try { raw = JSON.parse(text ?? 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}"`);

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

@@ -2,9 +2,10 @@
  * 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).
+ * this scenario at this hash — with exactly the opaque steps the entry says QA accepted (#923) — and
+ * whose `valid_from` is the entry's `approvedAt`. A lock line copied from elsewhere, re-pointed at
+ * another decision, backdated, or given an acceptance nobody recorded 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.
@@ -14,6 +15,7 @@ import { computeDecisionId, computeEntryHash } from '../decisions/decision-ident
 import { DecisionEntry, storedEntryErrors } from '../decisions/decision-schema';
 import { safeYamlParse } from '../utils/safe-yaml-parse';
 import { HeadSnapshot, headFileText, posixRel, readTextOrNull } from './contract-git';
+import { sameJson } from './contract-hash';
 import { ContractLock, isHumanApproved, LockEntry } from './contract-schema';
 import type { UncommittedEntry } from './lock-vs-git-head';
 
@@ -38,8 +40,10 @@ function loadDecision(projectRoot: string, unitDir: string, id: string, snap: He
 
 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}`;
+  const listed = Array.isArray(d.payload?.scenarios) ? d.payload!.scenarios as Array<{ id?: unknown; hash?: unknown; acceptedOpaque?: unknown }> : [];
+  const item = listed.find((s) => s && s.id === scenario && s.hash === lockEntry.hash);
+  if (!item) return `decision ${d.id} does not approve ${scenario} at hash ${lockEntry.hash}`;
+  if (!sameJson(item.acceptedOpaque ?? [], lockEntry.acceptedOpaque ?? [])) return `decision ${d.id} does not accept the opaque step(s) the lock entry of ${scenario} lists (acceptedOpaque)`;
   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;
 }

package/src/decisions/git-head-trust.ts

@@ -6,6 +6,7 @@
  * did not. Outside git, or for a file git does not track, nothing is trusted. Never throws.
  */
 import { execFileSync } from 'child_process';
+import * as fs from 'fs';
 import * as path from 'path';
 
 /** stdout of a git command run in `cwd`, or null when git fails (no repo, no HEAD, untracked path…). */
@@ -17,6 +18,49 @@ export function gitOutput(cwd: string, args: string[]): string | null {
   }
 }
 
+/**
+ * The text of each `<rev>:<path>` spec, read by ONE `git cat-file --batch` in `cwd` (`./path` is relative
+ * to it): null where git holds no such file; null for the whole call when git fails.
+ */
+export function gitFileTexts(cwd: string, specs: string[]): Array<string | null> | null {
+  if (specs.length === 0) return [];
+  if (specs.some((s) => /[\r\n]/.test(s))) return null;
+  let out: Buffer;
+  try {
+    out = execFileSync('git', ['cat-file', '--batch'], { cwd, input: `${specs.join('\n')}\n`, stdio: ['pipe', 'pipe', 'ignore'], maxBuffer: 256 * 1024 * 1024, timeout: 60000 });
+  } catch {
+    return null;
+  }
+  // Each answer: `<oid> <type> <size>\n<content>\n`, or `<spec> missing\n` (also `ambiguous`).
+  const texts: Array<string | null> = [];
+  let at = 0;
+  for (let i = 0; i < specs.length; i++) {
+    const eol = out.indexOf(0x0a, at);
+    if (eol < 0) return null;
+    const header = out.subarray(at, eol).toString('utf8').split(' ');
+    at = eol + 1;
+    if (header.length !== 3 || !/^\d+$/.test(header[2])) { texts.push(null); continue; }
+    const size = Number(header[2]);
+    texts.push(header[1] === 'blob' ? out.subarray(at, at + size).toString('utf8') : null);
+    at += size + 1;
+  }
+  return texts;
+}
+
+/**
+ * Whether `cwd` is in a shallow clone. git < 2.15 does not know `--is-shallow-repository` and echoes it
+ * back, so only an exact `true` / `false` is an answer; otherwise the `shallow` file in the git directory
+ * (common dir, or the git dir) decides, and when not even that can be found the clone is taken as shallow
+ * — its history is then unknown, which fails closed for the callers that ask.
+ */
+export function isShallowRepository(cwd: string): boolean {
+  const answer = gitOutput(cwd, ['rev-parse', '--is-shallow-repository'])?.trim();
+  if (answer === 'true' || answer === 'false') return answer === 'true';
+  const dirs = ['--git-common-dir', '--git-dir'].map((flag) => gitOutput(cwd, ['rev-parse', flag])?.trim())
+    .filter((d): d is string => !!d && !d.startsWith('-'));
+  return dirs.length === 0 || dirs.some((d) => fs.existsSync(path.join(path.resolve(cwd, d), 'shallow')));
+}
+
 /** The committed text of `abs` (a file inside `projectRoot`), or null when git HEAD has no such file. */
 export function committedText(projectRoot: string, abs: string): string | null {
   const rel = path.relative(projectRoot, abs).split(path.sep).join('/');

package/src/decisions/legacy-waiver-migration.ts

@@ -125,11 +125,18 @@ export function commitWaiverSync(projectRoot: string, unit: string, slug: string
   }
 }
 
-/** Record a waiver given now on the CLI; supersedes the waiver in force for that obligation, if any. */
+/**
+ * Record a waiver given now on the CLI; supersedes the waiver in force for that obligation, if any.
+ * The same waiver again records nothing — unless the one in force was imported (`where: migrated`):
+ * re-confirming it on a terminal is how a human vouches for a migrated waiver its legacy record cannot
+ * (decision.in-run), so it always writes the `cli` decision that supersedes it (#925).
+ */
 export function recordWaiver(projectRoot: string, unit: string, obligation: string, w: LegacyWaiver): AppendResult {
   const scope = unitDecisionScope(projectRoot, unit);
   if (!scope) throw new Error(`Cannot record a waiver: "${unit}" does not name exactly one unit under qa/screens, qa/flows or qa/api.`);
   const current = effectiveWaiverEntries(readDecisions(projectRoot, scope, { kind: 'waiver' }).entries).get(obligation);
-  if (current && sameWaiver(asLegacyWaiver(current), w)) return { status: 'already-recorded', entry: current, path: current.path };
+  if (current && current.source?.where !== 'migrated' && sameWaiver(asLegacyWaiver(current), w)) {
+    return { status: 'already-recorded', entry: current, path: current.path };
+  }
   return appendDecision(projectRoot, scope, waiverDraft(obligation, w, { by: gitUserName(projectRoot), where: 'cli' }, current?.id));
 }

package/src/harness/gates/in-run-decision-check.ts

@@ -11,10 +11,13 @@
  *
  * A MIGRATED waiver (DOS-13.5) was reviewed when its legacy record was committed — the only record the
  * import trusts — so it is judged by THAT commit (migrated-waiver-review.ts), never by its own decision
- * file: in-run when the record was committed after the run started, or, with no run to compare,
- * after the decision file appeared. Holding it to its decision file's commit would make every legacy
- * project's waivers in-run the day they are imported (phase 09). An entry HEAD's legacy file does not
- * vouch for — absent, uncommitted, different — is judged as any other.
+ * file: in-run when the record was committed after the run started, or — run start or not (#925) —
+ * when it could not have been the import's source: not strictly before the decision file, the unit's
+ * import marker or the project's adoption of 3.3 appeared. Holding it to its decision file's commit would make
+ * every legacy project's waivers in-run the day they are imported (phase 09). An entry HEAD's legacy
+ * file does not vouch for — absent, uncommitted, different, introduced beyond the commits the walk
+ * reads (#924) or at a shallow clone's boundary — is judged as any other; in the last two cases an
+ * in-run finding says why.
  */
 import * as fs from 'fs';
 import * as path from 'path';
@@ -22,7 +25,7 @@ import { DECISION_FILE_PATH } from '../../decisions/decision-file';
 import { DecisionVisibility } from '../../decisions/decision-schema';
 import { gitOutput } from '../../decisions/git-head-trust';
 import { readDecisions } from '../../decisions/read-decisions';
-import { decisionFirstSeenMs, migratedWaiverReviewedAt } from './migrated-waiver-review';
+import { migratedWaiverReview } from './migrated-waiver-review';
 
 export const IN_RUN_KINDS = ['gate-override', 'waiver', 'contract-approval'] as const;
 export const IN_RUN_RULE = 'decision.in-run';
@@ -60,18 +63,18 @@ const isInRunKind = (kind: string): boolean => (IN_RUN_KINDS as readonly string[
 export function inRunDecisions(projectRoot: string, scopes: string[], runStart: string | null, committed: Set<string> | null): InRunDecision[] {
   const out: InRunDecision[] = [];
   const after = (t: string): boolean => !!runStart && Date.parse(t) > Date.parse(runStart);
+  const migratedReview = committed ? migratedWaiverReview(projectRoot) : null;
   for (const scope of scopes) {
     for (const e of readDecisions(projectRoot, scope).entries) {
       if (!isInRunKind(e.kind)) continue;
+      // A migrated waiver re-confirmed on a terminal is replaced: the new decision is judged on its own.
+      if (e.superseded_by && e.source?.where === 'migrated') continue;
       const rel = path.relative(projectRoot, e.path).split(path.sep).join('/');
       const why: string[] = [];
-      const legacyAt = committed ? migratedWaiverReviewedAt(projectRoot, scope, e) : null;
-      if (legacyAt) {
-        if (runStart ? after(legacyAt) : Date.parse(legacyAt) > decisionFirstSeenMs(projectRoot, rel, e.path)) {
-          why.push(runStart
-            ? `migrated: its legacy record was committed at ${legacyAt}, after the run started ${runStart}`
-            : `migrated: its legacy record was committed at ${legacyAt}, after this decision first appeared`);
-        }
+      const migrated = migratedReview?.reviewOf(scope, e) ?? null;
+      if (migrated?.at) {
+        if (after(migrated.at)) why.push(`migrated: its legacy record was committed at ${migrated.at}, after the run started ${runStart}`);
+        if (migrated.notImported) why.push(migrated.notImported);
       } else if (committed && !committed.has(rel)) {
         why.push('not in git HEAD (never committed through review)');
       } else if (committed && runStart) {
@@ -82,6 +85,7 @@ export function inRunDecisions(projectRoot: string, scopes: string[], runStart:
       } else if (!committed && after(e.valid_from)) {
         why.push(`recorded ${e.valid_from}, after the run started ${runStart}`);
       }
+      if (why.length && migrated?.unvouched) why.push(migrated.unvouched);
       if (why.length) out.push({ id: e.id, kind: e.kind, path: rel, visibility: e.visibility, why });
     }
   }

package/src/harness/gates/migrated-waiver-import-bounds.ts

@@ -0,0 +1,103 @@
+/**
+ * Could a migrated waiver's legacy record have been the source of the import that wrote it? (#925)
+ *
+ * The one-time import (legacy-waiver-migration.ts) reads a record git HEAD ALREADY holds, and only
+ * before 3.3 takes over. So a genuine record was committed strictly before each of:
+ *   1. the decision file's first appearance — its first commit, else its creation on disk;
+ *   2. the unit's import marker `.sungen/migrations/<slug>.waivers-imported.json` — the commit that
+ *      added the one HEAD holds (an agent can delete or recreate the file, not that commit), else its
+ *      creation on disk; once it exists the import never reads that unit's legacy file again;
+ *   3. the project's adoption of 3.3 — the first commit that added any 3.3-only file: an import marker
+ *      or other `.sungen/migrations/` file, a decision file (`qa/**\/decisions/*.yaml`) or a contract lock
+ *      (`qa/**\/contracts.lock.yaml`). Only the 3.3 CLI writes them, and only committed ones count: a
+ *      legacy waiver is one written before the project's first reviewed 3.3 change. Mixed versions pay
+ *      for it: a waiver a pre-3.3 CLI writes after that commit must be re-confirmed on a terminal.
+ * A record failing any bound claims a migration that never happened: the decision is in-run.
+ *
+ * What stays open (the limit of any time-based check, as for ordinary decisions): a record forged and
+ * committed before the project's first 3.3 commit — indistinguishable from a real legacy waiver, as on
+ * a project adopting 3.3 for the very first time — and commit times forged with GIT_COMMITTER_DATE.
+ */
+import * as fs from 'fs';
+import * as path from 'path';
+import { committedText, gitOutput } from '../../decisions/git-head-trust';
+import { formatCommand } from '../../decisions/human-confirmation';
+import { importMarkerPath } from '../../decisions/legacy-waiver-migration';
+import type { ReadDecision } from '../../decisions/read-decisions';
+
+/** Files only the 3.3 CLI writes, as pathspecs relative to the project. */
+const ADOPTION_PATHSPECS = ['.sungen/migrations', ':(glob)qa/**/decisions/*.yaml', ':(glob)qa/**/contracts.lock.yaml'];
+
+/**
+ * What a human does about a migrated waiver its legacy record cannot vouch for: record it anew on a
+ * terminal (a `cli` decision that supersedes it — the superseded one is no longer judged), or accept it
+ * for one delivery.
+ */
+export const migratedWaiverRemedy = (scope: string, ob: string): string =>
+  `re-confirm it on a terminal: ${formatCommand(['sungen', 'journey', '--screen', scope.split('/').pop() ?? scope, '--waive', ob, '--reason', '…'])}, `
+  + 'then commit the new decision; or accept it once with `sungen delivery --accept-in-run`';
+
+const validMs = (iso: string | undefined): number | null => (iso && !Number.isNaN(Date.parse(iso)) ? Date.parse(iso) : null);
+const createdMs = (abs: string): number | null => {
+  try { const s = fs.statSync(abs); return s.birthtimeMs || s.mtimeMs; } catch { return null; }
+};
+
+/** One run's bounds: each decision's first appearance, each unit's marker and the project's adoption, read once. */
+export function migratedWaiverImportBounds(projectRoot: string) {
+  const relOf = (abs: string): string => path.relative(projectRoot, abs).split(path.sep).join('/');
+  const firstSeen = new Map<string, number>();
+  const markers = new Map<string, number | null>();
+  let adoption: number | null | undefined;
+
+  /** When a decision file first appeared: its first commit, else its creation (or last change) on disk. */
+  const decisionMs = (e: ReadDecision): number => {
+    if (!firstSeen.has(e.path)) {
+      const added = gitOutput(projectRoot, ['log', '--diff-filter=A', '--format=%cI', '--', relOf(e.path)])?.trim().split('\n').filter(Boolean).pop();
+      firstSeen.set(e.path, validMs(added) ?? createdMs(e.path) ?? Number.NEGATIVE_INFINITY);
+    }
+    return firstSeen.get(e.path)!;
+  };
+  const markerMs = (slug: string): number | null => {
+    if (!markers.has(slug)) {
+      const abs = importMarkerPath(projectRoot, slug);
+      const added = committedText(projectRoot, abs) !== null
+        ? validMs(gitOutput(projectRoot, ['log', '-1', '--diff-filter=A', '--format=%cI', '--', relOf(abs)])?.trim()) : null;
+      markers.set(slug, added ?? createdMs(abs));
+    }
+    return markers.get(slug)!;
+  };
+  const adoptionMs = (): number | null => {
+    if (adoption === undefined) {
+      const added = (gitOutput(projectRoot, ['log', '--diff-filter=A', '--format=%cI', '--', ...ADOPTION_PATHSPECS]) ?? '')
+        .split('\n').map((l) => validMs(l.trim())).filter((t): t is number => t !== null);
+      adoption = added.length ? Math.min(...added) : null;
+    }
+    return adoption;
+  };
+
+  /** The first bound a record committed at `legacy` (ms) crosses, or undefined. */
+  const boundCrossed = (slug: string, e: ReadDecision, legacy: number): string | undefined => {
+    const decision = decisionMs(e);
+    if (legacy > decision) return 'after this decision first appeared';
+    if (legacy === decision) return 'when this decision first appeared, not before it — an import only reads a record already committed';
+    const marker = markerMs(slug);
+    if (marker !== null && legacy >= marker) {
+      return `after this unit's waivers were imported (${relOf(importMarkerPath(projectRoot, slug))}, ${new Date(marker).toISOString()}) `
+        + '— from then on the import never reads the legacy file';
+    }
+    const adopted = adoptionMs();
+    if (adopted !== null && legacy >= adopted) {
+      return `after this project adopted sungen 3.3 (${new Date(adopted).toISOString()}: the first commit adding a .sungen/migrations/ file, `
+        + 'a decision or a contract lock) — a legacy waiver is one written before that';
+    }
+    return undefined;
+  };
+
+  return {
+    /** Why a record committed at `at` (state file of `slug`) cannot have been the source of `e`'s import; undefined when it can. */
+    notImported(slug: string, e: ReadDecision, at: string): string | undefined {
+      const why = boundCrossed(slug, e, Date.parse(at));
+      return why && `migrated: its legacy record was committed at ${at}, ${why}; ${migratedWaiverRemedy(e.scope, String(e.payload?.obligation))}`;
+    },
+  };
+}

package/src/harness/gates/migrated-waiver-review.ts

@@ -7,62 +7,115 @@
  *
  *   vouched   HEAD's state file holds the record (same reason, `at`, auditHashAtWaive) — reviewedAt is
  *             the commit time of the oldest commit in the unbroken run, back from HEAD, that holds it
- *   with a run start   in-run when reviewedAt is after it (the same test as any committed decision)
- *   without one        in-run when reviewedAt is after the decision file first appeared (its first
- *             commit, else its creation time): a genuine import always follows the commit it read
+ *   imported  the record could have been the import's source (#925) — always checked, run start or not:
+ *             committed strictly before the decision file, the unit's import marker and the project's
+ *             adoption of 3.3 first appeared (migrated-waiver-import-bounds.ts). Failing one, the decision
+ *             claims a migration that never happened → in-run, even at `gate --phase deliver`, which has
+ *             no run start.
+ *   with a run start   also in-run when reviewedAt is after it (the same test as any committed decision)
  * Anything else — no git, no such record in HEAD, a record that differs — is not vouched for: the
- * decision is judged as any other (`not in git HEAD`, or its own commit time).
+ * decision is judged as any other (`not in git HEAD`, or its own commit time). Only a rewritten history
+ * (a squash or rebase that folds the record's commit into the import's) can fail a genuine import; the
+ * finding says which bound it crossed.
+ *
+ * Nor is a record whose introducing commit is out of reach — judged as any other, with `unvouched`
+ * saying why, never vouched for by a later commit taken for its introduction: the walk reads at most
+ * MAX_COMMITS commits of a state file and the record is held by the commit before them too (#924), or
+ * the record reaches a shallow clone's boundary commit. One review reads each state file's history
+ * once (one `git log`, one `git cat-file --batch`), however many waivers share it.
  */
-import * as fs from 'fs';
-import * as path from 'path';
-import { committedText, gitOutput } from '../../decisions/git-head-trust';
+import { gitFileTexts, gitOutput, isShallowRepository } from '../../decisions/git-head-trust';
 import type { ReadDecision } from '../../decisions/read-decisions';
 import { asLegacyWaiver, isLegacyWaiver, sameWaiver } from '../../decisions/waiver-decisions';
 import { reportSlug } from '../unit-paths';
+import { migratedWaiverImportBounds, migratedWaiverRemedy } from './migrated-waiver-import-bounds';
 
-/** Commits of one state file the walk reads at most (each is one `git show`). */
+/** Commits of one state file the walk reads at most. */
 const MAX_COMMITS = 200;
 
-const parse = (text: string | null): { waivers?: Record<string, unknown> } | null => {
+type State = { waivers?: Record<string, unknown> } | null;
+/** A state file in git: HEAD's version and its newest MAX_COMMITS + 1 commits (newest first; `root`: no parent shown). */
+interface StateHistory { rel: string; head: State; commits: Array<{ at: string; state: State; root: boolean }> }
+
+/** A migrated waiver HEAD's legacy file holds: when it was reviewed, or why that cannot be said. */
+export interface MigratedReview {
+  /** When its legacy record was committed; null when that commit is out of reach (see `unvouched`). */
+  at: string | null;
+  /** Set with `at`: why the record cannot have been the import's source — the decision is in-run. */
+  notImported?: string;
+  /** Set when `at` is null: why the record vouches for nothing — the decision is judged as any other. */
+  unvouched?: string;
+}
+
+const parse = (text: string | null): State => {
   if (text === null) return null;
   try { return JSON.parse(text.replace(/^/, '')); } catch { return null; }
 };
 
-function holds(state: { waivers?: Record<string, unknown> } | null, e: ReadDecision, ob: string): boolean {
+function holds(state: State, e: ReadDecision, ob: string): boolean {
   const w = state?.waivers?.[ob];
   return isLegacyWaiver(w) && w.at === e.valid_from && sameWaiver(w, asLegacyWaiver(e));
 }
 
-/** The commit time of the oldest commit, in the unbroken run back from HEAD, whose state file holds the record. */
-function introducedAt(projectRoot: string, rel: string, e: ReadDecision, ob: string): string | null {
-  const log = gitOutput(projectRoot, ['log', `--max-count=${MAX_COMMITS}`, '--format=%H %cI', '--', rel]) ?? '';
-  let oldest: string | null = null;
-  for (const line of log.split('\n').filter(Boolean)) {
-    const [sha, at] = line.split(' ');
-    if (!holds(parse(gitOutput(projectRoot, ['show', `${sha}:./${rel}`])), e, ob)) break;
-    oldest = at;
-  }
-  return oldest && !Number.isNaN(Date.parse(oldest)) ? oldest : null;
+function readHistory(projectRoot: string, rel: string): StateHistory {
+  const log = (gitOutput(projectRoot, ['log', `--max-count=${MAX_COMMITS + 1}`, '--format=%H %cI %P', '--', rel]) ?? '')
+    .split('\n').filter(Boolean).map((line) => line.trim().split(' '));
+  const texts = gitFileTexts(projectRoot, [`HEAD:./${rel}`, ...log.map(([sha]) => `${sha}:./${rel}`)]);
+  return {
+    rel,
+    head: parse(texts?.[0] ?? null),
+    commits: log.map(([, at, ...parents], i) => ({ at, state: parse(texts?.[i + 1] ?? null), root: parents.length === 0 })),
+  };
 }
 
-/** When a migrated waiver's legacy record was committed, or null when nothing in git HEAD vouches for it. */
-export function migratedWaiverReviewedAt(projectRoot: string, scope: string, e: ReadDecision): string | null {
-  const ob = e.payload?.obligation;
-  if (e.kind !== 'waiver' || e.source?.where !== 'migrated' || typeof ob !== 'string') return null;
-  // The journey keys its state by the unit name it was given: `<name>`, or the catalog id for api units.
-  const slugs = new Set([scope.split('/').pop() ?? '', reportSlug(scope.replace(/^(screens|flows)\//, ''))]);
-  for (const slug of slugs) {
-    const file = path.join(projectRoot, '.sungen', 'journey', `${slug}.state.json`);
-    if (!holds(parse(committedText(projectRoot, file)), e, ob)) continue;
-    const at = introducedAt(projectRoot, path.relative(projectRoot, file).split(path.sep).join('/'), e, ob);
-    if (at) return at;
+/**
+ * The commit time of the oldest commit, in the unbroken run back from HEAD, whose state file holds the
+ * record. The walk reads MAX_COMMITS commits; the next one only says whether the last of them introduced it.
+ * In a shallow clone a commit with no parent shown is the boundary: every file seems to appear there, so a
+ * record reaching it has no known commit time.
+ */
+function introducedAt(h: StateHistory, e: ReadDecision, ob: string, scope: string, shallow: () => boolean): MigratedReview | null {
+  let run = 0;
+  while (run < h.commits.length && holds(h.commits[run].state, e, ob)) run++;
+  const unvouched = (why: string): MigratedReview => ({ at: null, unvouched: `migrated, but its legacy record cannot vouch for it: ${why}` });
+  if (run > MAX_COMMITS) {
+    return unvouched(`${h.rel} changed in more than ${MAX_COMMITS} commits, and the commit that introduced the record is older than all of them`);
   }
-  return null;
+  const oldest = run ? h.commits[run - 1] : null;
+  if (oldest?.root && shallow()) {
+    return unvouched(`the git history is shallow, so the record's real commit time is unknown — fetch the full history `
+      + `(\`git fetch --unshallow\`; \`fetch-depth: 0\` in CI), or ${migratedWaiverRemedy(scope, ob)}`);
+  }
+  return oldest && !Number.isNaN(Date.parse(oldest.at)) ? { at: oldest.at } : null;
 }
 
-/** When a decision file first appeared: its first commit, else its creation (or last change) on disk. */
-export function decisionFirstSeenMs(projectRoot: string, rel: string, abs: string): number {
-  const added = gitOutput(projectRoot, ['log', '--diff-filter=A', '--format=%cI', '--', rel])?.trim().split('\n').filter(Boolean).pop();
-  if (added && !Number.isNaN(Date.parse(added))) return Date.parse(added);
-  try { const s = fs.statSync(abs); return s.birthtimeMs || s.mtimeMs; } catch { return Number.NEGATIVE_INFINITY; }
+/** One run's reads for migrated waivers: each state file's history, decision's first commit and import marker, read once. */
+export function migratedWaiverReview(projectRoot: string) {
+  const histories = new Map<string, StateHistory>();
+  const bounds = migratedWaiverImportBounds(projectRoot);
+  let isShallow: boolean | undefined;
+  const shallow = (): boolean => (isShallow ??= isShallowRepository(projectRoot));
+  const historyOf = (rel: string): StateHistory => {
+    if (!histories.has(rel)) histories.set(rel, readHistory(projectRoot, rel));
+    return histories.get(rel)!;
+  };
+
+  return {
+    /** How a migrated waiver was reviewed; null when it is not one HEAD's legacy file holds (judged as any other). */
+    reviewOf(scope: string, e: ReadDecision): MigratedReview | null {
+      const ob = e.payload?.obligation;
+      if (e.kind !== 'waiver' || e.source?.where !== 'migrated' || typeof ob !== 'string') return null;
+      // The journey keys its state by the unit name it was given: `<name>`, or the catalog id for api units.
+      const slugs = new Set([scope.split('/').pop() ?? '', reportSlug(scope.replace(/^(screens|flows)\//, ''))]);
+      let unvouched: MigratedReview | null = null;
+      for (const slug of slugs) {
+        const h = historyOf(`.sungen/journey/${slug}.state.json`);
+        if (!holds(h.head, e, ob)) continue;
+        const review = introducedAt(h, e, ob, scope, shallow);
+        if (review?.at) return { at: review.at, notImported: bounds.notImported(slug, e, review.at) };
+        unvouched = unvouched ?? review;
+      }
+      return unvouched;
+    },
+  };
 }