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

package/dist/harness/gates/migrated-waiver-import-bounds.js

@@ -0,0 +1,141 @@
+"use strict";
+var __createBinding = (this && this.__createBinding) || (Object.create ? (function(o, m, k, k2) {
+    if (k2 === undefined) k2 = k;
+    var desc = Object.getOwnPropertyDescriptor(m, k);
+    if (!desc || ("get" in desc ? !m.__esModule : desc.writable || desc.configurable)) {
+      desc = { enumerable: true, get: function() { return m[k]; } };
+    }
+    Object.defineProperty(o, k2, desc);
+}) : (function(o, m, k, k2) {
+    if (k2 === undefined) k2 = k;
+    o[k2] = m[k];
+}));
+var __setModuleDefault = (this && this.__setModuleDefault) || (Object.create ? (function(o, v) {
+    Object.defineProperty(o, "default", { enumerable: true, value: v });
+}) : function(o, v) {
+    o["default"] = v;
+});
+var __importStar = (this && this.__importStar) || (function () {
+    var ownKeys = function(o) {
+        ownKeys = Object.getOwnPropertyNames || function (o) {
+            var ar = [];
+            for (var k in o) if (Object.prototype.hasOwnProperty.call(o, k)) ar[ar.length] = k;
+            return ar;
+        };
+        return ownKeys(o);
+    };
+    return function (mod) {
+        if (mod && mod.__esModule) return mod;
+        var result = {};
+        if (mod != null) for (var k = ownKeys(mod), i = 0; i < k.length; i++) if (k[i] !== "default") __createBinding(result, mod, k[i]);
+        __setModuleDefault(result, mod);
+        return result;
+    };
+})();
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.migratedWaiverRemedy = void 0;
+exports.migratedWaiverImportBounds = migratedWaiverImportBounds;
+/**
+ * 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.
+ */
+const fs = __importStar(require("fs"));
+const path = __importStar(require("path"));
+const git_head_trust_1 = require("../../decisions/git-head-trust");
+const human_confirmation_1 = require("../../decisions/human-confirmation");
+const legacy_waiver_migration_1 = require("../../decisions/legacy-waiver-migration");
+/** 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.
+ */
+const migratedWaiverRemedy = (scope, ob) => `re-confirm it on a terminal: ${(0, human_confirmation_1.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`';
+exports.migratedWaiverRemedy = migratedWaiverRemedy;
+const validMs = (iso) => (iso && !Number.isNaN(Date.parse(iso)) ? Date.parse(iso) : null);
+const createdMs = (abs) => {
+    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. */
+function migratedWaiverImportBounds(projectRoot) {
+    const relOf = (abs) => path.relative(projectRoot, abs).split(path.sep).join('/');
+    const firstSeen = new Map();
+    const markers = new Map();
+    let adoption;
+    /** When a decision file first appeared: its first commit, else its creation (or last change) on disk. */
+    const decisionMs = (e) => {
+        if (!firstSeen.has(e.path)) {
+            const added = (0, git_head_trust_1.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) => {
+        if (!markers.has(slug)) {
+            const abs = (0, legacy_waiver_migration_1.importMarkerPath)(projectRoot, slug);
+            const added = (0, git_head_trust_1.committedText)(projectRoot, abs) !== null
+                ? validMs((0, git_head_trust_1.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 = () => {
+        if (adoption === undefined) {
+            const added = ((0, git_head_trust_1.gitOutput)(projectRoot, ['log', '--diff-filter=A', '--format=%cI', '--', ...ADOPTION_PATHSPECS]) ?? '')
+                .split('\n').map((l) => validMs(l.trim())).filter((t) => 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, e, legacy) => {
+        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((0, legacy_waiver_migration_1.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, e, at) {
+            const why = boundCrossed(slug, e, Date.parse(at));
+            return why && `migrated: its legacy record was committed at ${at}, ${why}; ${(0, exports.migratedWaiverRemedy)(e.scope, String(e.payload?.obligation))}`;
+        },
+    };
+}
+//# sourceMappingURL=migrated-waiver-import-bounds.js.map

package/dist/harness/gates/migrated-waiver-import-bounds.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"migrated-waiver-import-bounds.js","sourceRoot":"","sources":["../../../src/harness/gates/migrated-waiver-import-bounds.ts"],"names":[],"mappings":"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"}

package/dist/harness/gates/migrated-waiver-review.d.ts

@@ -1,6 +1,16 @@
 import type { ReadDecision } from '../../decisions/read-decisions';
-/** When a migrated waiver's legacy record was committed, or null when nothing in git HEAD vouches for it. */
-export declare function migratedWaiverReviewedAt(projectRoot: string, scope: string, e: ReadDecision): string | null;
-/** When a decision file first appeared: its first commit, else its creation (or last change) on disk. */
-export declare function decisionFirstSeenMs(projectRoot: string, rel: string, abs: string): number;
+/** 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;
+}
+/** One run's reads for migrated waivers: each state file's history, decision's first commit and import marker, read once. */
+export declare function migratedWaiverReview(projectRoot: string): {
+    /** 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;
+};
 //# sourceMappingURL=migrated-waiver-review.d.ts.map

package/dist/harness/gates/migrated-waiver-review.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"migrated-waiver-review.d.ts","sourceRoot":"","sources":["../../../src/harness/gates/migrated-waiver-review.ts"],"names":[],"mappings":"AAkBA,OAAO,KAAK,EAAE,YAAY,EAAE,MAAM,gCAAgC,CAAC;AA6BnE,6GAA6G;AAC7G,wBAAgB,wBAAwB,CAAC,WAAW,EAAE,MAAM,EAAE,KAAK,EAAE,MAAM,EAAE,CAAC,EAAE,YAAY,GAAG,MAAM,GAAG,IAAI,CAY3G;AAED,yGAAyG;AACzG,wBAAgB,mBAAmB,CAAC,WAAW,EAAE,MAAM,EAAE,GAAG,EAAE,MAAM,EAAE,GAAG,EAAE,MAAM,GAAG,MAAM,CAIzF"}
+{"version":3,"file":"migrated-waiver-review.d.ts","sourceRoot":"","sources":["../../../src/harness/gates/migrated-waiver-review.ts"],"names":[],"mappings":"AA2BA,OAAO,KAAK,EAAE,YAAY,EAAE,MAAM,gCAAgC,CAAC;AAYnE,oGAAoG;AACpG,MAAM,WAAW,cAAc;IAC7B,qGAAqG;IACrG,EAAE,EAAE,MAAM,GAAG,IAAI,CAAC;IAClB,mGAAmG;IACnG,WAAW,CAAC,EAAE,MAAM,CAAC;IACrB,uGAAuG;IACvG,SAAS,CAAC,EAAE,MAAM,CAAC;CACpB;AA4CD,6HAA6H;AAC7H,wBAAgB,oBAAoB,CAAC,WAAW,EAAE,MAAM;IAWpD,kHAAkH;oBAClG,MAAM,KAAK,YAAY,GAAG,cAAc,GAAG,IAAI;EAgBlE"}

package/dist/harness/gates/migrated-waiver-review.js

@@ -1,40 +1,6 @@
 "use strict";
-var __createBinding = (this && this.__createBinding) || (Object.create ? (function(o, m, k, k2) {
-    if (k2 === undefined) k2 = k;
-    var desc = Object.getOwnPropertyDescriptor(m, k);
-    if (!desc || ("get" in desc ? !m.__esModule : desc.writable || desc.configurable)) {
-      desc = { enumerable: true, get: function() { return m[k]; } };
-    }
-    Object.defineProperty(o, k2, desc);
-}) : (function(o, m, k, k2) {
-    if (k2 === undefined) k2 = k;
-    o[k2] = m[k];
-}));
-var __setModuleDefault = (this && this.__setModuleDefault) || (Object.create ? (function(o, v) {
-    Object.defineProperty(o, "default", { enumerable: true, value: v });
-}) : function(o, v) {
-    o["default"] = v;
-});
-var __importStar = (this && this.__importStar) || (function () {
-    var ownKeys = function(o) {
-        ownKeys = Object.getOwnPropertyNames || function (o) {
-            var ar = [];
-            for (var k in o) if (Object.prototype.hasOwnProperty.call(o, k)) ar[ar.length] = k;
-            return ar;
-        };
-        return ownKeys(o);
-    };
-    return function (mod) {
-        if (mod && mod.__esModule) return mod;
-        var result = {};
-        if (mod != null) for (var k = ownKeys(mod), i = 0; i < k.length; i++) if (k[i] !== "default") __createBinding(result, mod, k[i]);
-        __setModuleDefault(result, mod);
-        return result;
-    };
-})();
 Object.defineProperty(exports, "__esModule", { value: true });
-exports.migratedWaiverReviewedAt = migratedWaiverReviewedAt;
-exports.decisionFirstSeenMs = decisionFirstSeenMs;
+exports.migratedWaiverReview = migratedWaiverReview;
 /**
  * When a MIGRATED waiver was reviewed (DOS-13.5, phase 09) — for `decision.in-run`.
  *
@@ -44,18 +10,28 @@ exports.decisionFirstSeenMs = decisionFirstSeenMs;
  *
  *   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.
  */
-const fs = __importStar(require("fs"));
-const path = __importStar(require("path"));
 const git_head_trust_1 = require("../../decisions/git-head-trust");
 const waiver_decisions_1 = require("../../decisions/waiver-decisions");
 const unit_paths_1 = require("../unit-paths");
-/** Commits of one state file the walk reads at most (each is one `git show`). */
+const migrated_waiver_import_bounds_1 = require("./migrated-waiver-import-bounds");
+/** Commits of one state file the walk reads at most. */
 const MAX_COMMITS = 200;
 const parse = (text) => {
     if (text === null)
@@ -71,46 +47,68 @@ function holds(state, e, ob) {
     const w = state?.waivers?.[ob];
     return (0, waiver_decisions_1.isLegacyWaiver)(w) && w.at === e.valid_from && (0, waiver_decisions_1.sameWaiver)(w, (0, waiver_decisions_1.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, rel, e, ob) {
-    const log = (0, git_head_trust_1.gitOutput)(projectRoot, ['log', `--max-count=${MAX_COMMITS}`, '--format=%H %cI', '--', rel]) ?? '';
-    let oldest = null;
-    for (const line of log.split('\n').filter(Boolean)) {
-        const [sha, at] = line.split(' ');
-        if (!holds(parse((0, git_head_trust_1.gitOutput)(projectRoot, ['show', `${sha}:./${rel}`])), e, ob))
-            break;
-        oldest = at;
-    }
-    return oldest && !Number.isNaN(Date.parse(oldest)) ? oldest : null;
-}
-/** When a migrated waiver's legacy record was committed, or null when nothing in git HEAD vouches for it. */
-function migratedWaiverReviewedAt(projectRoot, scope, e) {
-    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() ?? '', (0, unit_paths_1.reportSlug)(scope.replace(/^(screens|flows)\//, ''))]);
-    for (const slug of slugs) {
-        const file = path.join(projectRoot, '.sungen', 'journey', `${slug}.state.json`);
-        if (!holds(parse((0, git_head_trust_1.committedText)(projectRoot, file)), e, ob))
-            continue;
-        const at = introducedAt(projectRoot, path.relative(projectRoot, file).split(path.sep).join('/'), e, ob);
-        if (at)
-            return at;
-    }
-    return null;
+function readHistory(projectRoot, rel) {
+    const log = ((0, git_head_trust_1.gitOutput)(projectRoot, ['log', `--max-count=${MAX_COMMITS + 1}`, '--format=%H %cI %P', '--', rel]) ?? '')
+        .split('\n').filter(Boolean).map((line) => line.trim().split(' '));
+    const texts = (0, git_head_trust_1.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 decision file first appeared: its first commit, else its creation (or last change) on disk. */
-function decisionFirstSeenMs(projectRoot, rel, abs) {
-    const added = (0, git_head_trust_1.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;
+/**
+ * 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, e, ob, scope, shallow) {
+    let run = 0;
+    while (run < h.commits.length && holds(h.commits[run].state, e, ob))
+        run++;
+    const unvouched = (why) => ({ 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`);
     }
-    catch {
-        return Number.NEGATIVE_INFINITY;
+    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 ${(0, migrated_waiver_import_bounds_1.migratedWaiverRemedy)(scope, ob)}`);
     }
+    return oldest && !Number.isNaN(Date.parse(oldest.at)) ? { at: oldest.at } : null;
+}
+/** One run's reads for migrated waivers: each state file's history, decision's first commit and import marker, read once. */
+function migratedWaiverReview(projectRoot) {
+    const histories = new Map();
+    const bounds = (0, migrated_waiver_import_bounds_1.migratedWaiverImportBounds)(projectRoot);
+    let isShallow;
+    const shallow = () => (isShallow ?? (isShallow = (0, git_head_trust_1.isShallowRepository)(projectRoot)));
+    const historyOf = (rel) => {
+        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, e) {
+            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() ?? '', (0, unit_paths_1.reportSlug)(scope.replace(/^(screens|flows)\//, ''))]);
+            let unvouched = 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;
+        },
+    };
 }
 //# sourceMappingURL=migrated-waiver-review.js.map

package/dist/harness/gates/migrated-waiver-review.js.map

@@ -1 +1 @@
-{"version":3,"file":"migrated-waiver-review.js","sourceRoot":"","sources":["../../../src/harness/gates/migrated-waiver-review.ts"],"names":[],"mappings":"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"}
+{"version":3,"file":"migrated-waiver-review.js","sourceRoot":"","sources":["../../../src/harness/gates/migrated-waiver-review.ts"],"names":[],"mappings":"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"}

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@sun-asterisk/sungen",
-  "version": "3.3.0-alpha.2",
+  "version": "3.3.0-alpha.4",
   "description": "Deterministic E2E Test Compiler - Gherkin + Selectors → Playwright tests",
   "main": "src/index.ts",
   "types": "src/index.ts",
@@ -40,8 +40,8 @@
     "@babel/types": "^7.28.5",
     "@cucumber/gherkin": "^37.0.0",
     "@cucumber/messages": "^31.0.0",
-    "@sungen/driver-data-factory": "3.3.0-alpha.2",
-    "@sungen/driver-ui": "3.3.0-alpha.2",
+    "@sungen/driver-data-factory": "3.3.0-alpha.4",
+    "@sungen/driver-ui": "3.3.0-alpha.4",
     "chalk": "^5.6.2",
     "commander": "^14.0.2",
     "dotenv": "^17.2.3",

package/src/cli/commands/contract.ts

@@ -4,6 +4,9 @@
  *   approve --screen <u> [--scenario <id>] [--reason <text>]
  *       a human types a confirmation on a TTY; writes contracts.lock.yaml + a contract-approval
  *       decision. No TTY → refused with the exact command (exit 1).
+ *   approve --screen <u> --scenario <id> --accept-opaque [--reason <text>]
+ *       the same human act for the reviewed opaque trace steps of one approved free / impl:code
+ *       scenario (#923): bound to each step as it reads now (accept-opaque-steps.ts).
  *   check --screen <u> [--trace] [--json]
  *       rebuilds the verdict from .feature + lock + git HEAD + recorded traces (never from a report),
  *       writes .sungen/reports/<slug>-contract.json as output (secret-scanned first). Exit 2 on a hard
@@ -17,6 +20,7 @@ import * as fs from 'fs';
 import * as path from 'path';
 import { approveContract } from '../../contract/approve-contract';
 import { buildContractVerdict, ContractVerdict } from '../../contract/build-contract-verdict';
+import { LOW_IDENTITY_FINDING } from '../../contract/classify-trace-conformance';
 import { contractReportPath, writeContractReport } from '../../contract/contract-report-file';
 import { HARD_CLASSES, REVIEW_CLASSES } from '../../contract/contract-schema';
 import { processIO } from '../../decisions/human-confirmation';
@@ -33,7 +37,13 @@ const MARK: Record<string, string> = {
 const CHECK_TRACE_BUDGET_MS = 120_000;
 const UNPROVEN_HINT = "    → free / impl:code tests need their own config (outputDir 'test-results-free', trace: 'on', the sungen run-record reporter), then a fresh run (see `sungen contract derive`).";
 
-function printVerdict(v: ContractVerdict, reportFile: string): void {
+/** The command that recompiles a unit's spec — `sungen generate --screen|--flow|--api <unit>`. */
+function generateCommand(unit: { name: string; dir: string }): string {
+  const kind = path.relative(path.join(process.cwd(), 'qa'), unit.dir).split(path.sep)[0];
+  return `sungen generate --${kind === 'flows' ? 'flow' : kind === 'api' ? 'api' : 'screen'} ${unit.name}`;
+}
+
+function printVerdict(v: ContractVerdict, reportFile: string, generate: string): void {
   const L = console.log;
   const head = v.verdict === 'pass' ? '✓ PASS' : v.verdict === 'review'
     ? '⚖ REVIEW — changed, not weaker. Exit 0 here, but review blocks `sungen delivery` until QA re-approves' : '✗ FAIL';
@@ -64,7 +74,19 @@ function printVerdict(v: ContractVerdict, reportFile: string): void {
       : onlyUnproven ? "  → Re-run the free / impl:code tests with trace: 'on', then check again."
         : '  → Restore the approved checks in the .feature — or, if the change is intended, QA approves it on a terminal:');
   }
-  if (v.verdict !== 'pass' && !v.uncommitted.length && !onlyUnproven) L(`    sungen contract approve --screen ${v.unit}`);
+  // An opaque step is not cleared by re-approving (#923): QA reviews it, then accepts it as it reads now.
+  const acceptable = blocking.filter((s) => s.class === 'opaque' && s.trace?.opaque?.some((o) => !o.accepted)
+    && !s.findings.some((f) => f.detail.startsWith(LOW_IDENTITY_FINDING)));
+  if (v.verdict !== 'pass' && !v.uncommitted.length && !onlyUnproven && acceptable.length < blocking.length) L(`    sungen contract approve --screen ${v.unit}`);
+  for (const s of acceptable) {
+    L(`  → ${s.id}: QA reviews each opaque step above (verbatim, file:line); to accept them as they read now, on a terminal:`);
+    L(`    sungen contract approve --screen ${v.unit} --scenario ${s.id} --accept-opaque`);
+  }
+  // A weakened compiled scenario also leaves its spec out of step (#943): name the command that fixes the drift.
+  // (A free / impl:code scenario carries a trace summary; its test is hand-written, never regenerated.)
+  if (v.verdict === 'fail' && !v.uncommitted.length && v.scenarios.some((s) => !s.trace && HARD_CLASSES.has(s.class))) {
+    L(`  → After fixing the scenario, run \`${generate}\`: until the compiled spec is regenerated, \`sungen script-check\` reports drift.`);
+  }
   L(`  Report: ${path.relative(process.cwd(), reportFile)}`);
   L('');
 }
@@ -85,11 +107,20 @@ export function registerContractCommand(program: Command): void {
     .option('-s, --screen <name>', 'Screen / flow / api unit name')
     .option('--scenario <id>', 'Approve one scenario only (its ID, e.g. VP-LOGIN-001)')
     .option('--reason <text>', 'Why (recorded in the contract-approval decision)')
+    .option('--accept-opaque', 'With --scenario: accept the reviewed opaque trace step(s) of one approved free / impl:code scenario')
     .action(async (options) => {
       try {
         const unit = unitOrThrow(options.screen);
-        const r = await approveContract({ projectRoot: process.cwd(), unit: unit.name, scenario: options.scenario, reason: options.reason, io: processIO() });
+        const r = await approveContract({
+          projectRoot: process.cwd(), unit: unit.name, scenario: options.scenario, reason: options.reason, acceptOpaque: options.acceptOpaque === true, io: processIO(),
+        });
         if (r.status === 'nothing-to-approve') { console.log(`\n= Nothing to approve: every chosen scenario of ${unit.name} already matches its approved lock entry.\n`); return; }
+        if (r.status === 'nothing-to-accept') { console.log(`\n= Nothing to accept: every opaque step of ${options.scenario} is already accepted as it reads now.\n`); return; }
+        if (r.status === 'accepted') {
+          console.log(`\n✓ Accepted ${r.accepted?.length ?? 0} opaque step(s) of ${options.scenario} → ${path.relative(process.cwd(), r.lockPath)} (decision ${r.decisionId})`);
+          console.log('  Commit the lock and the decision through review, then re-run the free test with its trace: a trace older than the lock proves nothing.\n');
+          return;
+        }
         console.log(`\n✓ Approved ${r.approved.length} scenario(s)${r.removed.length ? `, removed ${r.removed.length}` : ''} → ${path.relative(process.cwd(), r.lockPath)} (decision ${r.decisionId})`);
         console.log('  Commit the lock and the decision through review: until they are in git HEAD, `sungen contract check` reports contract.lock-uncommitted.\n');
       } catch (error) {
@@ -116,7 +147,7 @@ export function registerContractCommand(program: Command): void {
         if (hits.length) throw new Error(`Refused to write the contract report — likely secret(s): ${hits.map((h) => `${h.where} ${h.reason}`).join('; ')}`);
         const file = writeContractReport(process.cwd(), verdict);
         if (options.json) console.log(JSON.stringify(verdict, null, 2));
-        else printVerdict(verdict, file);
+        else printVerdict(verdict, file, generateCommand(unit));
         process.exit(verdict.exitCode);
       } catch (error) {
         // Unreadable = not run (DOS-14.0): an earlier report must not outlive the inputs it judged.

package/src/contract/accept-opaque-steps.ts

@@ -0,0 +1,114 @@
+/**
+ * `sungen contract approve --screen <u> --scenario <id> --accept-opaque` — a QA accepts the reviewed
+ * opaque steps of ONE approved free / impl:code scenario (#923). An opaque step (a check on a JS value,
+ * an API request, an evaluate) is never compared by code, so without this an approved test that has one
+ * stays in review for good: re-approving changes nothing and contract.opaque-step allows no override.
+ * In order, like `approve` (approve-contract.ts), so a human never confirms something then refused:
+ *
+ *   1. the scenario must be approved AS IT READS NOW — its lock entry human-approved, intact, at the
+ *      current hash, and vouched for by its decision — else: approve it first
+ *   2. its verdict is rebuilt (buildContractVerdict, as `contract check`): the opaque steps must be the
+ *      ONLY thing holding it; anything else (changed, unproven, inconclusive, a `low` identity…) refuses
+ *      with its own fix. Every opaque step already accepted → nothing to accept, no prompt
+ *   3. each opaque step is shown verbatim with its file:line; on a TTY the human types the scenario id
+ *      and a one-time code — without one: refused with the exact command (an agent never runs this)
+ *   4. everything is read AGAIN: if the trace, the feature or the lock moved meanwhile → refused
+ *   5. a contract-approval decision records the scenario at its hash WITH the accepted steps (step + sha)
+ *      and the lock entry points at it (record-contract-approval.ts)
+ *
+ * The acceptance is bound to each step's sha (opaqueStepSha): a change to an accepted step, or a new
+ * approval of the scenario, brings it back to review.
+ *
+ * Trust boundary: the TTY confirmation guards this command, not the files. A lock entry AND a matching
+ * decision forged together and committed through review are trusted like any approval — git review
+ * is that boundary, here as for `approve`.
+ */
+import { gitUserName } from '../decisions/decision-source';
+import { formatCommand, requireTypedConfirmation } from '../decisions/human-confirmation';
+import type { ApproveInput, ApproveResult } from './approve-contract';
+import { buildContractVerdict } from './build-contract-verdict';
+import { LOW_IDENTITY_FINDING } from './classify-trace-conformance';
+import { canonicalJson } from './contract-hash';
+import { ContractScenario, isHumanApproved, OpaqueStep } from './contract-schema';
+import { resolveContractUnit } from './contract-units';
+import { lockPathFor, ReadLock, readLockFile } from './contracts-lock-file';
+import { loadContractScenarios } from './normalize-feature-steps';
+import { recordOpaqueAcceptance } from './record-contract-approval';
+import { unverifiedApprovals } from './verify-approval-decisions';
+
+/** Accepting reads the traces with `contract check`'s generous deadline, never the guard's ~3 s. */
+const ACCEPT_TRACE_BUDGET_MS = 120_000;
+/** Findings that never hold a scenario back may stand beside the opaque steps. */
+const HARMLESS = new Set(['strengthened', 'nondeterministic']);
+
+interface Plan { unitDir: string; unit: string; scenario: ContractScenario; lock: ReadLock; decisionId: string; opaque: OpaqueStep[]; fingerprint: string }
+
+const isLow = (detail: string): boolean => detail.startsWith(LOW_IDENTITY_FINDING);
+
+function plan(i: ApproveInput, id: string): Plan {
+  const unit = resolveContractUnit(i.projectRoot, i.unit);
+  const lock = readLockFile(lockPathFor(unit.dir));
+  const matches = loadContractScenarios(unit.dir, unit.name).filter((s) => s.id === id);
+  if (!matches.length) throw new Error(`--scenario ${id} names no scenario of ${i.unit}`);
+  if (matches.length > 1) throw new Error(`Refused: scenario id ${id} is used by ${matches.length} scenarios — an acceptance must name exactly one. Give each its own ID.`);
+  const sc = matches[0];
+  if (sc.implementation === 'compiled') throw new Error(`Refused: ${id} is compiled — only a free / impl:code test has trace steps to accept.`);
+  const entry = lock?.scenarios[id];
+  if (!lock || !isHumanApproved(entry) || lock.tampered.includes(id) || entry.hash !== sc.hash) {
+    throw new Error(`Refused: ${id} is not approved as it reads now — approve it first (\`sungen contract approve --screen ${i.unit} --scenario ${id}\`), re-run it with a trace, then accept its opaque steps.`);
+  }
+  // The entry an acceptance re-points must be QA's own: its decision (on disk) vouches for it as it is.
+  const [unvouched] = unverifiedApprovals(i.projectRoot, unit.dir, { schema: lock.schema, scenarios: { [id]: entry } }, new Set(), { root: i.projectRoot, timeoutMs: 0, blobs: null });
+  if (unvouched) throw new Error(`Refused: the lock entry of ${id} is not vouched for by its decision (${unvouched.detail}) — restore the lock from git, or approve the scenario again.`);
+
+  const v = buildContractVerdict(i.projectRoot, unit, { traceBudgetMs: ACCEPT_TRACE_BUDGET_MS });
+  const bad = v.uncommitted.find((u) => u.id === id && (u.change === 'tampered' || u.change === 'unverified'));
+  if (bad) throw new Error(`Refused: the lock entry of ${id} is ${bad.change} (${bad.detail}) — restore it from git before accepting anything.`);
+  const r = v.scenarios.find((s) => s.id === id);
+  const blocking = (r?.findings ?? []).filter((f) => !HARMLESS.has(f.class) && !(f.class === 'opaque' && !isLow(f.detail)));
+  if (blocking.length) {
+    const fix = blocking.some((f) => isLow(f.detail))
+      ? `run \`sungen contract check --screen ${i.unit} --trace\` (a real browser resolves the identity) first`
+      : `settle that first — \`sungen contract check --screen ${i.unit}\` names the fix`;
+    throw new Error(`Refused: accepting clears only opaque steps, and ${id} is also held by: ${blocking.map((f) => `${f.class}${f.step ? ` (step ${f.step})` : ''} — ${f.detail}`).join('; ')}. ${fix[0].toUpperCase()}${fix.slice(1)}.`);
+  }
+  const opaque = r?.trace?.opaque ?? [];
+  if (!opaque.length) throw new Error(`Refused: the trace of ${id} has no opaque step — nothing to accept (${r?.class ?? 'not judged'}).`);
+  return { unitDir: unit.dir, unit: unit.name, scenario: sc, lock, decisionId: entry.decisionId, opaque, fingerprint: canonicalJson({ lock, hash: sc.hash, opaque }) };
+}
+
+const describe = (o: OpaqueStep): string =>
+  `${o.accepted ? '=' : '◐'} step ${o.step}  opaque ${o.kind === 'assert' ? 'check' : 'step'} "${o.verbatim}"${o.where ? ` at ${o.where}` : ''}`
+  + `${o.replaces ? ` — replaces approved ${o.replaces}` : ''}${o.accepted ? '  (accepted before)' : ''}`;
+
+export async function acceptOpaqueSteps(i: ApproveInput): Promise<ApproveResult> {
+  const id = i.scenario;
+  if (!id) throw new Error('--accept-opaque needs --scenario <id>: an acceptance names the one scenario whose opaque steps QA reviewed');
+  const before = plan(i, id);
+  const lockPath = lockPathFor(before.unitDir);
+  if (before.opaque.every((o) => o.accepted)) return { status: 'nothing-to-accept', lockPath, approved: [], removed: [] };
+
+  const pending = before.opaque.filter((o) => !o.accepted);
+  await requireTypedConfirmation({
+    what: `accept ${pending.length} reviewed opaque step(s) of ${id} (${i.unit}) — steps sungen cannot compare, so they are never checked by code`,
+    phrase: id,
+    command: formatCommand(['sungen', 'contract', 'approve', '--screen', i.unit, '--scenario', id, '--accept-opaque', ...(i.reason ? ['--reason', i.reason] : [])]),
+    summary: [
+      ...before.opaque.map(describe),
+      `bound to each step as it reads now: a change to it, or a new approval of ${id}, brings it back to review`,
+      `${id} stays approved at hash ${before.scenario.hash}; its lock entry moves from decision ${before.decisionId} to the new one`,
+      `recorded by: ${gitUserName(i.projectRoot)}`,
+    ],
+    io: i.io,
+  });
+
+  const after = plan(i, id);
+  if (after.fingerprint !== before.fingerprint) {
+    throw new Error('Refused: the trace, the feature or the lock changed while you were confirming — nothing was written. Run the command again and review the new summary.');
+  }
+  const { decisionId } = recordOpaqueAcceptance({
+    projectRoot: i.projectRoot, unitDir: after.unitDir, unit: after.unit, scenario: after.scenario, reason: i.reason, lock: after.lock,
+    accepted: after.opaque.map((o) => ({ step: o.step, sha: o.sha })),
+  });
+  return { status: 'accepted', lockPath, decisionId, approved: [id], removed: [], accepted: after.opaque };
+}