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

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;
 }