@invarn/cibuild 2.3.5 → 2.3.7

package/dist/src/yaml/steps/structural-facts.test.js

@@ -801,6 +801,52 @@ describe('deriveSpanFacts — declared highlight extents vs rendered background
             { kind: 'span_mismatch', elementId: 'a', rendered: 'y', reference: 'right' },
         ]);
     });
+    // ── Foreground-color spans (partial-color emphasis), capability-gated. ──
+    test('a color span with the right extent but the wrong color yields span_color_mismatch', () => {
+        expect(deriveSpanFacts({ pillText: [{ start: 19, end: 30, text: 'special offer', color: '#ffffff' }] }, { pillText: { text: 'special offer', color: '#ffdc23' } }, true)).toEqual([
+            {
+                kind: 'span_color_mismatch',
+                elementId: 'pillText',
+                extent: 'special offer',
+                rendered: '#ffffff',
+                reference: '#ffdc23',
+            },
+        ]);
+    });
+    test('a color span matching extent AND color (case-insensitive) produces no fact', () => {
+        expect(deriveSpanFacts({ pillText: [{ start: 19, end: 30, text: 'special offer', color: '#FFDC23' }] }, { pillText: { text: 'special offer', color: '#ffdc23' } }, true)).toEqual([]);
+    });
+    test('a capable dump rendering NO span at all fails a color declaration (dropped emphasis)', () => {
+        expect(deriveSpanFacts({}, { pillText: { text: 'special offer', color: '#ffdc23' } }, true)).toEqual([
+            { kind: 'span_mismatch', elementId: 'pillText', rendered: '', reference: 'special offer' },
+        ]);
+    });
+    test('a color declaration against a color-blind dump stays silent (capability gate)', () => {
+        // Old emitter: no spanChannels marker → colorCapable false. Its silence
+        // is "cannot see", never "no color span rendered".
+        expect(deriveSpanFacts({}, { pillText: { text: 'special offer', color: '#ffdc23' } }, false)).toEqual([]);
+        expect(deriveSpanFacts({}, { pillText: { text: 'special offer', color: '#ffdc23' } })).toEqual([]);
+    });
+    test('a color-only rendered span never satisfies a BACKGROUND declaration (channel-scoped)', () => {
+        expect(deriveSpanFacts({ pillText: [{ start: 0, end: 5, text: 'offer', color: '#ffdc23' }] }, { pillText: { text: 'offer', background: '#ffe45e' } }, true)).toEqual([
+            { kind: 'span_mismatch', elementId: 'pillText', rendered: '', reference: 'offer' },
+        ]);
+    });
+    test('a declaration carrying BOTH channels needs both satisfied', () => {
+        const rendered = {
+            pillText: [{ start: 0, end: 5, text: 'offer', background: '#ffe45e', color: '#ffdc23' }],
+        };
+        expect(deriveSpanFacts(rendered, { pillText: { text: 'offer', background: '#ffe45e', color: '#ffdc23' } }, true)).toEqual([]);
+        expect(deriveSpanFacts(rendered, { pillText: { text: 'offer', background: '#ffe45e', color: '#1b1b1b' } }, true)).toEqual([
+            {
+                kind: 'span_color_mismatch',
+                elementId: 'pillText',
+                extent: 'offer',
+                rendered: '#ffdc23',
+                reference: '#1b1b1b',
+            },
+        ]);
+    });
 });
 describe('deriveLineFacts — declared line split vs rendered laid-out lines', () => {
     test('rendered lines matching the declared split produce no fact', () => {

package/dist/src/yaml/steps/ui-fidelity-render-android.d.ts

@@ -12,12 +12,17 @@
  *      Optional reference-provenance sidecar (manifest-driven multi-state path):
  *      `"render_locale": "<locale>"` plus
  *      `"provenance": { "<ScreenName>": { figmaNode, locale, resolved, exportedAt } }`.
- *      When `render_locale` is present, each screen's reference is gated on its
- *      provenance METADATA (never pixels/OCR): absent, unprovenanced,
- *      `resolved == false`, or `locale != render_locale` → status
- *      `unverifiable` for that screen, so a rotten reference fails loud instead
- *      of yielding a confident-but-false PASS. Content differences (copy,
- *      geometry) are NOT gated here — they stay soft, judged findings.
+ *      The gate arms whenever a screen's provenance is present (or, legacy, when
+ *      `render_locale` is declared) and checks provenance METADATA only (never
+ *      pixels/OCR). An absent reference — or an unprovenanced screen while
+ *      `render_locale` is declared — is FATAL: status `unverifiable`, failing
+ *      loud instead of yielding a confident-but-false PASS. `resolved == false`
+ *      (placeholder copy) or `locale != render_locale` downgrade ONLY the copy
+ *      channel: the screen renders and is judged on geometry, colors, typeface,
+ *      spans, and lines, while copy comparisons are skipped and reported as a
+ *      per-screen `copy_advisory` (`copy_unverifiable` + reason) in
+ *      protocol-result.json. Content differences (copy, geometry) are NOT gated
+ *      here — they stay soft, judged findings.
  *   2. Extracts and validates the shipped Gradle project shipped as
  *      `.ci/inputs/package.tar.gz` (single project root carrying a settings
  *      script, bounded extracted size, safe member paths).

package/dist/src/yaml/steps/ui-fidelity-render-android.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"ui-fidelity-render-android.d.ts","sourceRoot":"","sources":["../../../../src/yaml/steps/ui-fidelity-render-android.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;GAgDG;AAEH,OAAO,EAAE,gBAAgB,EAAE,MAAM,WAAW,CAAC;AAC7C,OAAO,KAAK,EAAE,OAAO,EAAE,QAAQ,EAAE,MAAM,gBAAgB,CAAC;AACxD,OAAO,KAAK,EAAE,qBAAqB,EAAE,MAAM,wBAAwB,CAAC;AAMpE,sDAAsD;AACtD,MAAM,WAAW,6BAA6B;IAC5C;;;;OAIG;IACH,KAAK,CAAC,EAAE,MAAM,GAAG,MAAM,CAAC;IACxB;;;;OAIG;IACH,WAAW,CAAC,EAAE,MAAM,CAAC;CACtB;AAED;;;GAGG;AACH,eAAO,MAAM,mBAAmB,yBAAyB,CAAC;AAE1D,iDAAiD;AACjD,eAAO,MAAM,eAAe,6BAA8B,CAAC;AAC3D,MAAM,MAAM,aAAa,GAAG,CAAC,OAAO,eAAe,CAAC,CAAC,MAAM,CAAC,CAAC;AAE7D;;;;GAIG;AACH,eAAO,MAAM,sBAAsB,EAAE,aAAwB,CAAC;AAE9D,mDAAmD;AACnD,eAAO,MAAM,iBAAiB,6BAA8B,CAAC;AAC7D,MAAM,MAAM,eAAe,GAAG,CAAC,OAAO,iBAAiB,CAAC,CAAC,MAAM,CAAC,CAAC;AAEjE;;;GAGG;AACH,eAAO,MAAM,wBAAwB,EAAE,eAA0B,CAAC;AAElE,gFAAgF;AAChF,eAAO,MAAM,wBAAwB,mBAAmB,CAAC;AAEzD,4DAA4D;AAC5D,eAAO,MAAM,gBAAgB,0BAA0B,CAAC;AAExD;;;;GAIG;AACH,wBAAgB,iBAAiB,CAAC,IAAI,EAAE,MAAM,GAAG,OAAO,CAEvD;AAED,8EAA8E;AAC9E,MAAM,WAAW,yBAAyB;IACxC,KAAK,EAAE,MAAM,CAAC;IACd,UAAU,EAAE,MAAM,CAAC;IACnB;;;;OAIG;IACH,aAAa,CAAC,EAAE,aAAa,CAAC;IAC9B;;;OAGG;IACH,WAAW,CAAC,EAAE,MAAM,CAAC;IACrB;;;;OAIG;IACH,eAAe,CAAC,EAAE,eAAe,CAAC;CACnC;AAq+BD;;;;;;;GAOG;AACH,wBAAgB,2BAA2B,CAAC,MAAM,EAAE,yBAAyB,GAAG,MAAM,CAqBrF;AAED;;;GAGG;AACH,qBAAa,mCAAoC,SAAQ,gBAAgB;IACvE,yBAAyB,CACvB,OAAO,EAAE,6BAA6B,EACtC,IAAI,EAAE,MAAM,CAAC,MAAM,EAAE,MAAM,CAAC,EAC5B,OAAO,EAAE,QAAQ,GAChB,qBAAqB,EAAE;IAepB,OAAO,CACX,MAAM,EAAE,6BAA6B,EACrC,IAAI,EAAE,MAAM,CAAC,MAAM,EAAE,MAAM,CAAC,EAC5B,OAAO,EAAE,QAAQ,GAChB,OAAO,CAAC,OAAO,CAAC;CA0EpB"}
+{"version":3,"file":"ui-fidelity-render-android.d.ts","sourceRoot":"","sources":["../../../../src/yaml/steps/ui-fidelity-render-android.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;GAqDG;AAEH,OAAO,EAAE,gBAAgB,EAAE,MAAM,WAAW,CAAC;AAC7C,OAAO,KAAK,EAAE,OAAO,EAAE,QAAQ,EAAE,MAAM,gBAAgB,CAAC;AACxD,OAAO,KAAK,EAAE,qBAAqB,EAAE,MAAM,wBAAwB,CAAC;AAMpE,sDAAsD;AACtD,MAAM,WAAW,6BAA6B;IAC5C;;;;OAIG;IACH,KAAK,CAAC,EAAE,MAAM,GAAG,MAAM,CAAC;IACxB;;;;OAIG;IACH,WAAW,CAAC,EAAE,MAAM,CAAC;CACtB;AAED;;;GAGG;AACH,eAAO,MAAM,mBAAmB,yBAAyB,CAAC;AAE1D,iDAAiD;AACjD,eAAO,MAAM,eAAe,6BAA8B,CAAC;AAC3D,MAAM,MAAM,aAAa,GAAG,CAAC,OAAO,eAAe,CAAC,CAAC,MAAM,CAAC,CAAC;AAE7D;;;;GAIG;AACH,eAAO,MAAM,sBAAsB,EAAE,aAAwB,CAAC;AAE9D,mDAAmD;AACnD,eAAO,MAAM,iBAAiB,6BAA8B,CAAC;AAC7D,MAAM,MAAM,eAAe,GAAG,CAAC,OAAO,iBAAiB,CAAC,CAAC,MAAM,CAAC,CAAC;AAEjE;;;GAGG;AACH,eAAO,MAAM,wBAAwB,EAAE,eAA0B,CAAC;AAElE,gFAAgF;AAChF,eAAO,MAAM,wBAAwB,mBAAmB,CAAC;AAEzD,4DAA4D;AAC5D,eAAO,MAAM,gBAAgB,0BAA0B,CAAC;AAExD;;;;GAIG;AACH,wBAAgB,iBAAiB,CAAC,IAAI,EAAE,MAAM,GAAG,OAAO,CAEvD;AAED,8EAA8E;AAC9E,MAAM,WAAW,yBAAyB;IACxC,KAAK,EAAE,MAAM,CAAC;IACd,UAAU,EAAE,MAAM,CAAC;IACnB;;;;OAIG;IACH,aAAa,CAAC,EAAE,aAAa,CAAC;IAC9B;;;OAGG;IACH,WAAW,CAAC,EAAE,MAAM,CAAC;IACrB;;;;OAIG;IACH,eAAe,CAAC,EAAE,eAAe,CAAC;CACnC;AAkiCD;;;;;;;GAOG;AACH,wBAAgB,2BAA2B,CAAC,MAAM,EAAE,yBAAyB,GAAG,MAAM,CAqBrF;AAED;;;GAGG;AACH,qBAAa,mCAAoC,SAAQ,gBAAgB;IACvE,yBAAyB,CACvB,OAAO,EAAE,6BAA6B,EACtC,IAAI,EAAE,MAAM,CAAC,MAAM,EAAE,MAAM,CAAC,EAC5B,OAAO,EAAE,QAAQ,GAChB,qBAAqB,EAAE;IAepB,OAAO,CACX,MAAM,EAAE,6BAA6B,EACrC,IAAI,EAAE,MAAM,CAAC,MAAM,EAAE,MAAM,CAAC,EAC5B,OAAO,EAAE,QAAQ,GAChB,OAAO,CAAC,OAAO,CAAC;CA0EpB"}

package/dist/src/yaml/steps/ui-fidelity-render-android.js

@@ -12,12 +12,17 @@
  *      Optional reference-provenance sidecar (manifest-driven multi-state path):
  *      `"render_locale": "<locale>"` plus
  *      `"provenance": { "<ScreenName>": { figmaNode, locale, resolved, exportedAt } }`.
- *      When `render_locale` is present, each screen's reference is gated on its
- *      provenance METADATA (never pixels/OCR): absent, unprovenanced,
- *      `resolved == false`, or `locale != render_locale` → status
- *      `unverifiable` for that screen, so a rotten reference fails loud instead
- *      of yielding a confident-but-false PASS. Content differences (copy,
- *      geometry) are NOT gated here — they stay soft, judged findings.
+ *      The gate arms whenever a screen's provenance is present (or, legacy, when
+ *      `render_locale` is declared) and checks provenance METADATA only (never
+ *      pixels/OCR). An absent reference — or an unprovenanced screen while
+ *      `render_locale` is declared — is FATAL: status `unverifiable`, failing
+ *      loud instead of yielding a confident-but-false PASS. `resolved == false`
+ *      (placeholder copy) or `locale != render_locale` downgrade ONLY the copy
+ *      channel: the screen renders and is judged on geometry, colors, typeface,
+ *      spans, and lines, while copy comparisons are skipped and reported as a
+ *      per-screen `copy_advisory` (`copy_unverifiable` + reason) in
+ *      protocol-result.json. Content differences (copy, geometry) are NOT gated
+ *      here — they stay soft, judged findings.
  *   2. Extracts and validates the shipped Gradle project shipped as
  *      `.ci/inputs/package.tar.gz` (single project root carrying a settings
  *      script, bounded extracted size, safe member paths).
@@ -207,44 +212,80 @@ function setUnverifiable(entry, code, message) {
   entry.error = { code: code, message: sanitizeMessage(message) };
 }
 
-// Inlined twin of src/yaml/steps/fidelity-reference-provenance.ts (this script
+// Inlined twins of src/yaml/steps/fidelity-reference-provenance.ts (this script
 // ships self-contained and cannot import it). The render-step integration tests
-// exercise BOTH against the same fixtures so they cannot silently drift. Returns
-// a { code, message } fault, or null when the reference is verifiable.
-function provenanceFault(screen, provenance, renderLocale, referenceExists) {
-  var hasProvenance =
+// exercise BOTH against the same fixtures so they cannot silently drift.
+
+// Provenance is only "present" when the fields the gate reasons over are there.
+// A partial object (e.g. a hand-dropped { figmaNode }) is treated as no
+// provenance — verifiable is earned only through the full export path.
+function hasReferenceProvenance(provenance) {
+  return (
     provenance != null &&
     typeof provenance === 'object' &&
     typeof provenance.locale === 'string' &&
-    typeof provenance.resolved === 'boolean';
-  if (!hasProvenance) {
+    typeof provenance.resolved === 'boolean'
+  );
+}
+
+// Assesses one screen's reference. Returns { fault, copyAdvisory }: a fatal
+// fault makes the screen unverifiable; a copy advisory downgrades only the
+// copy channel (the screen still renders and is judged on geometry, colors,
+// typeface, spans, and lines). An absent reference wins over a downgrade —
+// there is nothing to judge against.
+function assessReferenceProvenance(screen, provenance, renderLocale, referenceExists) {
+  if (!hasReferenceProvenance(provenance)) {
+    if (renderLocale !== null) {
+      return {
+        fault: {
+          code: 'NO_PROVENANCE',
+          message:
+            'reference for ' + screen + ' has no export provenance; a reference is ' +
+            'verifiable only when exported through the deterministic path',
+        },
+        copyAdvisory: null,
+      };
+    }
+    // Unarmed: the caller keeps legacy behaviour (including its own
+    // reference-existence check).
+    return { fault: null, copyAdvisory: null };
+  }
+  if (!referenceExists) {
     return {
-      code: 'NO_PROVENANCE',
-      message:
-        'reference for ' + screen + ' has no export provenance; a reference is ' +
-        'verifiable only when exported through the deterministic path',
+      fault: {
+        code: 'REFERENCE_ABSENT',
+        message: 'reference image for ' + screen + ' is absent',
+      },
+      copyAdvisory: null,
     };
   }
   if (provenance.resolved === false) {
     return {
-      code: 'UNRESOLVED_REFERENCE',
-      message:
-        'reference for ' + screen + ' still has unresolved copy placeholders ' +
-        '(resolved=false) — export it with the copy filled in',
+      fault: null,
+      copyAdvisory: {
+        code: 'copy_unverifiable',
+        reason: 'unresolved_placeholders',
+        message:
+          'reference for ' + screen + ' carries unresolved copy placeholders ' +
+          '(resolved=false); copy comparisons are skipped — geometry, color, ' +
+          'typeface, span, and line judging still hold',
+      },
     };
   }
-  if (provenance.locale !== renderLocale) {
+  if (renderLocale !== null && provenance.locale !== renderLocale) {
     return {
-      code: 'LOCALE_MISMATCH',
-      message:
-        'reference for ' + screen + ' is locale "' + provenance.locale +
-        '" but the render locale is "' + renderLocale + '"',
+      fault: null,
+      copyAdvisory: {
+        code: 'copy_unverifiable',
+        reason: 'locale_mismatch',
+        message:
+          'reference for ' + screen + ' is locale "' + provenance.locale +
+          '" but the render locale is "' + renderLocale + '"; copy comparisons ' +
+          'are skipped — geometry, color, typeface, span, and line judging still hold',
+      },
     };
   }
-  if (!referenceExists) {
-    return { code: 'REFERENCE_ABSENT', message: 'reference image for ' + screen + ' is absent' };
-  }
-  return null;
+  return { fault: null, copyAdvisory: null };
 }
 
 function outputTail(result) {
@@ -808,6 +849,7 @@ function main() {
       screen: screen,
       status: 'render_failed',
       error: null,
+      copy_advisory: null,
       reference_image_path: null,
       rendered_image_path: null,
       aligned_image_path: null,
@@ -859,22 +901,46 @@ function main() {
     }
     var referenceExists = !!(sourceStat && sourceStat.isFile());
 
-    if (renderLocale) {
-      // Provenance enforcement: a reference that is absent, unprovenanced,
-      // unresolved, or in the wrong locale is UNVERIFIABLE (hard, loud) — not a
-      // render_failed and never a silent PASS.
-      var fault = provenanceFault(
+    // Provenance assessment, armed whenever this screen's provenance rides in
+    // params (the references/ snapshot lifts it automatically) or the run
+    // declares a render locale (legacy arming, which keeps NO_PROVENANCE
+    // fatal). Fatal faults (reference absent, no provenance while armed) make
+    // the screen UNVERIFIABLE — hard, loud, never a silent PASS. Unresolved
+    // placeholders and locale mismatches downgrade ONLY the copy channel: the
+    // screen renders and is judged on geometry, colors, typeface, spans, and
+    // lines, while copy comparisons are skipped and reported as a structured
+    // copy_unverifiable advisory.
+    var screenProvenance = provenanceMap[entry.screen];
+    if (renderLocale !== null || hasReferenceProvenance(screenProvenance)) {
+      var assessment = assessReferenceProvenance(
         entry.screen,
-        provenanceMap[entry.screen],
+        screenProvenance,
         renderLocale,
         referenceExists
       );
-      if (fault) {
-        setUnverifiable(entry, fault.code, fault.message);
+      if (assessment.fault) {
+        setUnverifiable(entry, assessment.fault.code, assessment.fault.message);
         return;
       }
+      if (assessment.copyAdvisory) {
+        entry.copy_advisory = {
+          code: assessment.copyAdvisory.code,
+          reason: assessment.copyAdvisory.reason,
+          message: sanitizeMessage(assessment.copyAdvisory.message),
+        };
+        // Copy comparisons are unverifiable for this screen: drop its
+        // reference text so no copy facts (text_mismatch / text_missing) are
+        // derived downstream.
+        if (referenceText && referenceText[entry.screen]) {
+          delete referenceText[entry.screen];
+        }
+        log(
+          entry.screen + ': copy channel downgraded (' +
+            assessment.copyAdvisory.reason + '), non-copy judging proceeds'
+        );
+      }
     } else if (!referenceExists) {
-      // Legacy (no render locale declared): an absent reference stays a
+      // Legacy (no provenance, no render locale): an absent reference stays a
       // render_failed REFERENCE_MISSING, exactly as before.
       setError(
         entry,

package/dist/src/yaml/steps/ui-fidelity-render-android.test.js

@@ -540,7 +540,7 @@ describe('android render runtime — render + trim (happy path)', () => {
         expect(doc.screens.map((s) => s.status)).toEqual(['rendered', 'rendered']);
     });
 });
-describe('android render runtime — reference provenance (UNVERIFIABLE)', () => {
+describe('android render runtime — reference provenance', () => {
     const GOOD_PROV = {
         figmaNode: '12:345',
         locale: 'en',
@@ -554,7 +554,7 @@ describe('android render runtime — reference provenance (UNVERIFIABLE)', () =>
         stageArchive(project, gradleProjectEntries());
         return project;
     }
-    test('a reference with no provenance is unverifiable', async () => {
+    test('a reference with no provenance stays unverifiable when a render locale is declared', async () => {
         const project = provProject({
             screens: { XProof: 'x.png' },
             render_locale: 'en',
@@ -566,31 +566,62 @@ describe('android render runtime — reference provenance (UNVERIFIABLE)', () =>
         expect(screen?.status).toBe('unverifiable');
         expect(screen?.error?.code).toBe('NO_PROVENANCE');
     });
-    test('a placeholder reference (resolved=false) is unverifiable', async () => {
+    test('a placeholder reference (resolved=false) renders and downgrades only the copy channel', async () => {
         const project = provProject({
             screens: { XProof: 'x.png' },
             render_locale: 'en',
             provenance: { XProof: { ...GOOD_PROV, resolved: false } },
         });
         writeReference(project, 'x.png');
-        runScript(project, await buildScript());
+        const run = runScript(project, await buildScript(), { FAKE_ROBORAZZI_SCREENS: 'XProof' });
+        expect(run.status).toBe(0);
         const screen = readResult(project).screens.find((s) => s.screen === 'XProof');
-        expect(screen?.status).toBe('unverifiable');
-        expect(screen?.error?.code).toBe('UNRESOLVED_REFERENCE');
+        expect(screen?.status).toBe('rendered');
+        expect(screen?.error).toBeNull();
+        expect(screen?.copy_advisory?.code).toBe('copy_unverifiable');
+        expect(screen?.copy_advisory?.reason).toBe('unresolved_placeholders');
+    });
+    test('the placeholder downgrade is identical without a render_locale (same input, same verdict)', async () => {
+        // Live evidence bld_5f8dc6330c9e61f578297f00 / bld_c92bc240ab8aac7dfe258b27:
+        // the same resolved:false reference was judged in one run and refused in
+        // the other purely because of the optional render_locale param.
+        const project = provProject({
+            screens: { XProof: 'x.png' },
+            provenance: { XProof: { ...GOOD_PROV, resolved: false } },
+        });
+        writeReference(project, 'x.png');
+        const run = runScript(project, await buildScript(), { FAKE_ROBORAZZI_SCREENS: 'XProof' });
+        expect(run.status).toBe(0);
+        const screen = readResult(project).screens.find((s) => s.screen === 'XProof');
+        expect(screen?.status).toBe('rendered');
+        expect(screen?.copy_advisory?.reason).toBe('unresolved_placeholders');
     });
-    test('an Italian reference against an English render is unverifiable', async () => {
+    test('an Italian reference against an English render downgrades the copy channel', async () => {
         const project = provProject({
             screens: { XProof: 'x.png' },
             render_locale: 'en',
             provenance: { XProof: { ...GOOD_PROV, locale: 'it' } },
         });
         writeReference(project, 'x.png');
-        runScript(project, await buildScript());
+        const run = runScript(project, await buildScript(), { FAKE_ROBORAZZI_SCREENS: 'XProof' });
+        expect(run.status).toBe(0);
         const screen = readResult(project).screens.find((s) => s.screen === 'XProof');
-        expect(screen?.status).toBe('unverifiable');
-        expect(screen?.error?.code).toBe('LOCALE_MISMATCH');
+        expect(screen?.status).toBe('rendered');
+        expect(screen?.copy_advisory?.code).toBe('copy_unverifiable');
+        expect(screen?.copy_advisory?.reason).toBe('locale_mismatch');
     });
-    test('an absent reference with good provenance is unverifiable', async () => {
+    test('locale comparison requires a declared render_locale — its absence skips only that', async () => {
+        const project = provProject({
+            screens: { XProof: 'x.png' },
+            provenance: { XProof: { ...GOOD_PROV, locale: 'it' } },
+        });
+        writeReference(project, 'x.png');
+        runScript(project, await buildScript(), { FAKE_ROBORAZZI_SCREENS: 'XProof' });
+        const screen = readResult(project).screens.find((s) => s.screen === 'XProof');
+        expect(screen?.status).toBe('rendered');
+        expect(screen?.copy_advisory ?? null).toBeNull();
+    });
+    test('an absent reference with good provenance stays fatal (REFERENCE_ABSENT)', async () => {
         const project = provProject({
             screens: { XProof: 'x.png' },
             render_locale: 'en',
@@ -602,7 +633,17 @@ describe('android render runtime — reference provenance (UNVERIFIABLE)', () =>
         expect(screen?.status).toBe('unverifiable');
         expect(screen?.error?.code).toBe('REFERENCE_ABSENT');
     });
-    test('a good provenanced reference renders normally (a content diff is left to the judge)', async () => {
+    test('an absent reference is fatal even without a render_locale (armed by provenance presence)', async () => {
+        const project = provProject({
+            screens: { XProof: 'x.png' },
+            provenance: { XProof: GOOD_PROV },
+        });
+        runScript(project, await buildScript());
+        const screen = readResult(project).screens.find((s) => s.screen === 'XProof');
+        expect(screen?.status).toBe('unverifiable');
+        expect(screen?.error?.code).toBe('REFERENCE_ABSENT');
+    });
+    test('a good provenanced reference renders normally with no copy advisory', async () => {
         const project = provProject({
             screens: { XProof: 'x.png' },
             render_locale: 'en',
@@ -614,8 +655,9 @@ describe('android render runtime — reference provenance (UNVERIFIABLE)', () =>
         const screen = readResult(project).screens.find((s) => s.screen === 'XProof');
         expect(screen?.status).toBe('rendered');
         expect(screen?.error).toBeNull();
+        expect(screen?.copy_advisory ?? null).toBeNull();
     });
-    test('independent verdicts: a sibling stays rendered while one state is unverifiable', async () => {
+    test('independent verdicts: a clean sibling carries no advisory while the placeholder state does', async () => {
         const project = provProject({
             screens: { XProof: 'x.png', YProof: 'y.png' },
             render_locale: 'en',
@@ -623,19 +665,52 @@ describe('android render runtime — reference provenance (UNVERIFIABLE)', () =>
         });
         writeReference(project, 'x.png');
         writeReference(project, 'y.png');
-        runScript(project, await buildScript(), { FAKE_ROBORAZZI_SCREENS: 'XProof' });
+        runScript(project, await buildScript(), { FAKE_ROBORAZZI_SCREENS: 'XProof,YProof' });
         const doc = readResult(project);
-        expect(doc.screens.find((s) => s.screen === 'XProof')?.status).toBe('rendered');
+        const x = doc.screens.find((s) => s.screen === 'XProof');
+        expect(x?.status).toBe('rendered');
+        expect(x?.copy_advisory ?? null).toBeNull();
         const y = doc.screens.find((s) => s.screen === 'YProof');
-        expect(y?.status).toBe('unverifiable');
-        expect(y?.error?.code).toBe('UNRESOLVED_REFERENCE');
+        expect(y?.status).toBe('rendered');
+        expect(y?.copy_advisory?.reason).toBe('unresolved_placeholders');
     });
-    test('without a render_locale, provenance is not enforced (legacy behaviour)', async () => {
+    test('without provenance and without a render_locale, nothing is enforced (legacy behaviour)', async () => {
         const project = provProject({ screens: { XProof: 'x.png' } });
         writeReference(project, 'x.png');
         runScript(project, await buildScript(), { FAKE_ROBORAZZI_SCREENS: 'XProof' });
         const screen = readResult(project).screens.find((s) => s.screen === 'XProof');
         expect(screen?.status).toBe('rendered');
+        expect(screen?.copy_advisory ?? null).toBeNull();
+    });
+    test('a downgraded copy channel derives no copy facts while geometry facts still hold', async () => {
+        // The fake layout dump carries a text node ("tag": "TAG") that clips its
+        // parent. With reference text that mismatches, a clean run derives a
+        // text_mismatch fact — a downgraded run must derive NONE while keeping
+        // the clipped_by_parent geometry fact.
+        const factKinds = async (resolved) => {
+            const project = provProject({
+                screens: { XProof: 'x.png' },
+                render_locale: 'en',
+                provenance: { XProof: { ...GOOD_PROV, resolved } },
+                reference_text: { XProof: { tag: 'DIFFERENT' } },
+            });
+            writeReference(project, 'x.png');
+            runScript(project, await buildScript(), {
+                FAKE_ROBORAZZI_SCREENS: 'XProof',
+                FAKE_ROBORAZZI_LAYOUT: '1',
+            });
+            const screen = readResult(project).screens.find((s) => s.screen === 'XProof');
+            const structural = (screen?.structural?.facts ?? []).map((f) => f.kind);
+            const appearance = (screen?.structural?.appearance?.facts ?? []).map((f) => f.kind);
+            return [...structural, ...appearance];
+        };
+        const clean = await factKinds(true);
+        expect(clean).toContain('text_mismatch');
+        expect(clean).toContain('clipped_by_parent');
+        const downgraded = await factKinds(false);
+        expect(downgraded).not.toContain('text_mismatch');
+        expect(downgraded).not.toContain('text_missing');
+        expect(downgraded).toContain('clipped_by_parent');
     });
 });
 describe('android render runtime — error isolation', () => {

package/dist/src/yaml/steps/ui-fidelity-render.d.ts

@@ -8,6 +8,16 @@
  *   1. Reads `.ci/inputs/params.json`
  *      ({ "screens": { "<ViewTypeName>": "<referenceFileBasename>" } });
  *      reference images live at `.ci/inputs/<basename>`.
+ *      Optional reference-provenance sidecar: `"render_locale": "<locale>"`
+ *      plus `"provenance": { "<ViewTypeName>": { figmaNode, locale, resolved,
+ *      exportedAt } }`. The gate arms per screen from provenance presence and
+ *      checks METADATA only (never pixels/OCR): an absent reference is FATAL
+ *      (status `unverifiable`, REFERENCE_ABSENT); `resolved == false` or
+ *      `locale != render_locale` downgrade ONLY the copy channel — the screen
+ *      renders and is judged on every non-copy channel, and the downgrade
+ *      rides as a per-screen `copy_advisory` (`copy_unverifiable` + reason).
+ *      Unprovenanced screens keep legacy behaviour (no NO_PROVENANCE arming
+ *      on iOS).
  *   2. Synthesizes a throwaway SwiftPM harness package that depends on the
  *      user's package and contains ONE executable target per screen, so a
  *      compile failure for one screen (unknown view type, unavailable init)

package/dist/src/yaml/steps/ui-fidelity-render.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"ui-fidelity-render.d.ts","sourceRoot":"","sources":["../../../../src/yaml/steps/ui-fidelity-render.ts"],"names":[],"mappings":"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"}
+{"version":3,"file":"ui-fidelity-render.d.ts","sourceRoot":"","sources":["../../../../src/yaml/steps/ui-fidelity-render.ts"],"names":[],"mappings":"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"}