@invarn/cibuild 2.3.6 → 2.3.8

package/dist/src/yaml/steps/fidelity-reference-provenance.d.ts

@@ -1,14 +1,30 @@
 /**
- * Reference-provenance gate.
+ * Reference-provenance assessment.
  *
  * A UI-fidelity reference is a PNG the gate cannot read, so reference validity
  * is asserted at export time as provenance metadata (`figmaNode`, `locale`,
  * `resolved`, `exportedAt`) and the gate checks that METADATA — never the
- * pixels, never via OCR. A reference that is absent, unprovenanced,
- * placeholder-bearing (`resolved == false`), or in a locale other than the
- * render's is UNVERIFIABLE: a hard, mechanical verdict that fails loud instead
- * of producing a confident-but-false PASS, and that kills the ad-hoc-Figma-fetch
- * root cause (an ad-hoc fetch has no provenance, so it is Unverifiable).
+ * pixels, never via OCR.
+ *
+ * The assessment splits into two severities:
+ *
+ *  - FATAL faults → status `unverifiable` for the screen. A reference that is
+ *    absent has nothing to judge against (`REFERENCE_ABSENT`); a screen with no
+ *    provenance while the run declares a render locale keeps the legacy
+ *    `NO_PROVENANCE` verdict (verifiable is earned only through the full
+ *    export path, and it kills the ad-hoc-Figma-fetch root cause).
+ *  - COPY-CHANNEL downgrades → the screen still renders and is judged on
+ *    geometry, colors, typeface, spans, and lines; only copy comparisons are
+ *    skipped, reported as a structured `copy_unverifiable` advisory naming the
+ *    reason. Placeholder copy (`resolved == false`) and locale mismatches are
+ *    normal customer reality — dynamic content is designed as placeholders —
+ *    so the product adapts instead of refusing the screen or telling the
+ *    customer to re-export.
+ *
+ * The check arms whenever per-screen provenance rides in params; a declared
+ * render locale is only required for the locale comparison itself. Screens
+ * with neither provenance nor a declared locale are unarmed and keep the
+ * caller's legacy behaviour.
  *
  * Content differences (copy wording, geometry) are deliberately NOT evaluated
  * here — those are soft, judged findings that legitimately drift between
@@ -27,19 +43,45 @@ export interface ReferenceProvenanceMeta {
     resolved?: boolean;
     exportedAt?: string;
 }
-/** A reason a reference cannot be honestly judged. */
+/** A reason a reference cannot be honestly judged at all. */
 export interface ProvenanceFault {
-    /** Stable machine code (NO_PROVENANCE / UNRESOLVED_REFERENCE / …). */
+    /** Stable machine code (NO_PROVENANCE / REFERENCE_ABSENT). */
     code: string;
     /** Human/agent-readable reason, naming the screen. */
     message: string;
 }
+/** Advisory code for a downgraded copy channel. */
+export declare const COPY_UNVERIFIABLE_CODE = "copy_unverifiable";
+/**
+ * A copy-channel downgrade: the screen is judged normally except that copy
+ * comparisons are unverifiable for the named reason.
+ */
+export interface CopyChannelAdvisory {
+    code: typeof COPY_UNVERIFIABLE_CODE;
+    reason: 'unresolved_placeholders' | 'locale_mismatch';
+    /** Human/agent-readable reason, naming the screen. */
+    message: string;
+}
+/** The outcome of assessing one screen's reference provenance. */
+export interface ProvenanceAssessment {
+    /** Fatal: the screen cannot be judged (status `unverifiable`), or null. */
+    fault: ProvenanceFault | null;
+    /** Copy-channel downgrade riding in the per-screen result, or null. */
+    copyAdvisory: CopyChannelAdvisory | null;
+}
 /** The per-state status string written to protocol-result.json. */
 export declare const UNVERIFIABLE_STATUS = "unverifiable";
 /**
- * Returns the reason a reference is UNVERIFIABLE, or null when it is verifiable.
- * Checks metadata then existence; order is irrelevant for single-fault inputs
- * but deterministic when several faults coincide.
+ * Whether provenance is "present" for arming purposes. A partial object (e.g.
+ * a hand-dropped `{ figmaNode }`) is treated as no provenance — verifiable is
+ * earned only through the full export path.
+ */
+export declare function hasReferenceProvenance(p: ReferenceProvenanceMeta | null | undefined): p is ReferenceProvenanceMeta;
+/**
+ * Assesses one screen's reference. Returns a fatal fault (screen
+ * `unverifiable`), a copy-channel advisory (screen judged, copy skipped), or
+ * neither. Never both: an absent reference wins over a downgrade because there
+ * is nothing to judge against.
  */
-export declare function provenanceFault(screen: string, provenance: ReferenceProvenanceMeta | null | undefined, renderLocale: string, referenceExists: boolean): ProvenanceFault | null;
+export declare function assessReferenceProvenance(screen: string, provenance: ReferenceProvenanceMeta | null | undefined, renderLocale: string | null, referenceExists: boolean): ProvenanceAssessment;
 //# sourceMappingURL=fidelity-reference-provenance.d.ts.map

package/dist/src/yaml/steps/fidelity-reference-provenance.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"fidelity-reference-provenance.d.ts","sourceRoot":"","sources":["../../../../src/yaml/steps/fidelity-reference-provenance.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;;;;;GAqBG;AAEH,qEAAqE;AACrE,MAAM,WAAW,uBAAuB;IACtC,SAAS,CAAC,EAAE,MAAM,CAAC;IACnB,MAAM,CAAC,EAAE,MAAM,CAAC;IAChB,QAAQ,CAAC,EAAE,OAAO,CAAC;IACnB,UAAU,CAAC,EAAE,MAAM,CAAC;CACrB;AAED,sDAAsD;AACtD,MAAM,WAAW,eAAe;IAC9B,sEAAsE;IACtE,IAAI,EAAE,MAAM,CAAC;IACb,sDAAsD;IACtD,OAAO,EAAE,MAAM,CAAC;CACjB;AAED,mEAAmE;AACnE,eAAO,MAAM,mBAAmB,iBAAiB,CAAC;AAgBlD;;;;GAIG;AACH,wBAAgB,eAAe,CAC7B,MAAM,EAAE,MAAM,EACd,UAAU,EAAE,uBAAuB,GAAG,IAAI,GAAG,SAAS,EACtD,YAAY,EAAE,MAAM,EACpB,eAAe,EAAE,OAAO,GACvB,eAAe,GAAG,IAAI,CAgCxB"}
+{"version":3,"file":"fidelity-reference-provenance.d.ts","sourceRoot":"","sources":["../../../../src/yaml/steps/fidelity-reference-provenance.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;GAqCG;AAEH,qEAAqE;AACrE,MAAM,WAAW,uBAAuB;IACtC,SAAS,CAAC,EAAE,MAAM,CAAC;IACnB,MAAM,CAAC,EAAE,MAAM,CAAC;IAChB,QAAQ,CAAC,EAAE,OAAO,CAAC;IACnB,UAAU,CAAC,EAAE,MAAM,CAAC;CACrB;AAED,6DAA6D;AAC7D,MAAM,WAAW,eAAe;IAC9B,8DAA8D;IAC9D,IAAI,EAAE,MAAM,CAAC;IACb,sDAAsD;IACtD,OAAO,EAAE,MAAM,CAAC;CACjB;AAED,mDAAmD;AACnD,eAAO,MAAM,sBAAsB,sBAAsB,CAAC;AAE1D;;;GAGG;AACH,MAAM,WAAW,mBAAmB;IAClC,IAAI,EAAE,OAAO,sBAAsB,CAAC;IACpC,MAAM,EAAE,yBAAyB,GAAG,iBAAiB,CAAC;IACtD,sDAAsD;IACtD,OAAO,EAAE,MAAM,CAAC;CACjB;AAED,kEAAkE;AAClE,MAAM,WAAW,oBAAoB;IACnC,2EAA2E;IAC3E,KAAK,EAAE,eAAe,GAAG,IAAI,CAAC;IAC9B,uEAAuE;IACvE,YAAY,EAAE,mBAAmB,GAAG,IAAI,CAAC;CAC1C;AAED,mEAAmE;AACnE,eAAO,MAAM,mBAAmB,iBAAiB,CAAC;AAElD;;;;GAIG;AACH,wBAAgB,sBAAsB,CACpC,CAAC,EAAE,uBAAuB,GAAG,IAAI,GAAG,SAAS,GAC5C,CAAC,IAAI,uBAAuB,CAO9B;AAED;;;;;GAKG;AACH,wBAAgB,yBAAyB,CACvC,MAAM,EAAE,MAAM,EACd,UAAU,EAAE,uBAAuB,GAAG,IAAI,GAAG,SAAS,EACtD,YAAY,EAAE,MAAM,GAAG,IAAI,EAC3B,eAAe,EAAE,OAAO,GACvB,oBAAoB,CAqDtB"}

package/dist/src/yaml/steps/fidelity-reference-provenance.js

@@ -1,14 +1,30 @@
 /**
- * Reference-provenance gate.
+ * Reference-provenance assessment.
  *
  * A UI-fidelity reference is a PNG the gate cannot read, so reference validity
  * is asserted at export time as provenance metadata (`figmaNode`, `locale`,
  * `resolved`, `exportedAt`) and the gate checks that METADATA — never the
- * pixels, never via OCR. A reference that is absent, unprovenanced,
- * placeholder-bearing (`resolved == false`), or in a locale other than the
- * render's is UNVERIFIABLE: a hard, mechanical verdict that fails loud instead
- * of producing a confident-but-false PASS, and that kills the ad-hoc-Figma-fetch
- * root cause (an ad-hoc fetch has no provenance, so it is Unverifiable).
+ * pixels, never via OCR.
+ *
+ * The assessment splits into two severities:
+ *
+ *  - FATAL faults → status `unverifiable` for the screen. A reference that is
+ *    absent has nothing to judge against (`REFERENCE_ABSENT`); a screen with no
+ *    provenance while the run declares a render locale keeps the legacy
+ *    `NO_PROVENANCE` verdict (verifiable is earned only through the full
+ *    export path, and it kills the ad-hoc-Figma-fetch root cause).
+ *  - COPY-CHANNEL downgrades → the screen still renders and is judged on
+ *    geometry, colors, typeface, spans, and lines; only copy comparisons are
+ *    skipped, reported as a structured `copy_unverifiable` advisory naming the
+ *    reason. Placeholder copy (`resolved == false`) and locale mismatches are
+ *    normal customer reality — dynamic content is designed as placeholders —
+ *    so the product adapts instead of refusing the screen or telling the
+ *    customer to re-export.
+ *
+ * The check arms whenever per-screen provenance rides in params; a declared
+ * render locale is only required for the locale comparison itself. Screens
+ * with neither provenance nor a declared locale are unarmed and keep the
+ * caller's legacy behaviour.
  *
  * Content differences (copy wording, geometry) are deliberately NOT evaluated
  * here — those are soft, judged findings that legitimately drift between
@@ -20,50 +36,76 @@
  * tests exercise that inlined copy end-to-end against the same fixtures, so the
  * two cannot silently drift.
  */
+/** Advisory code for a downgraded copy channel. */
+export const COPY_UNVERIFIABLE_CODE = 'copy_unverifiable';
 /** The per-state status string written to protocol-result.json. */
 export const UNVERIFIABLE_STATUS = 'unverifiable';
-function hasProvenance(p) {
-    // 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.
+/**
+ * Whether provenance is "present" for arming purposes. A partial object (e.g.
+ * a hand-dropped `{ figmaNode }`) is treated as no provenance — verifiable is
+ * earned only through the full export path.
+ */
+export function hasReferenceProvenance(p) {
     return (p != null &&
         typeof p === 'object' &&
         typeof p.locale === 'string' &&
         typeof p.resolved === 'boolean');
 }
 /**
- * Returns the reason a reference is UNVERIFIABLE, or null when it is verifiable.
- * Checks metadata then existence; order is irrelevant for single-fault inputs
- * but deterministic when several faults coincide.
+ * Assesses one screen's reference. Returns a fatal fault (screen
+ * `unverifiable`), a copy-channel advisory (screen judged, copy skipped), or
+ * neither. Never both: an absent reference wins over a downgrade because there
+ * is nothing to judge against.
  */
-export function provenanceFault(screen, provenance, renderLocale, referenceExists) {
-    if (!hasProvenance(provenance)) {
-        return {
-            code: 'NO_PROVENANCE',
-            message: `reference for ${screen} has no export provenance; a reference is ` +
-                `verifiable only when exported through the deterministic path`,
-        };
+export 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: no provenance rode in and no locale was declared — the caller
+        // keeps its legacy behaviour (including its own reference-existence check).
+        return { fault: null, copyAdvisory: null };
     }
-    if (provenance.resolved === false) {
+    if (!referenceExists) {
         return {
-            code: 'UNRESOLVED_REFERENCE',
-            message: `reference for ${screen} still has unresolved copy placeholders ` +
-                `(resolved=false) — export it with the copy filled in`,
+            fault: {
+                code: 'REFERENCE_ABSENT',
+                message: `reference image for ${screen} is absent`,
+            },
+            copyAdvisory: null,
         };
     }
-    if (provenance.locale !== renderLocale) {
+    if (provenance.resolved === false) {
         return {
-            code: 'LOCALE_MISMATCH',
-            message: `reference for ${screen} is locale "${provenance.locale}" but the ` +
-                `render locale is "${renderLocale}"`,
+            fault: null,
+            copyAdvisory: {
+                code: COPY_UNVERIFIABLE_CODE,
+                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 (!referenceExists) {
+    if (renderLocale !== null && provenance.locale !== renderLocale) {
         return {
-            code: 'REFERENCE_ABSENT',
-            message: `reference image for ${screen} is absent`,
+            fault: null,
+            copyAdvisory: {
+                code: COPY_UNVERIFIABLE_CODE,
+                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`,
+            },
         };
     }
-    return null;
+    return { fault: null, copyAdvisory: null };
 }
 //# sourceMappingURL=fidelity-reference-provenance.js.map

package/dist/src/yaml/steps/fidelity-reference-provenance.test.d.ts

@@ -1,14 +1,22 @@
 /**
- * Unit tests for the reference-provenance gate.
+ * Unit tests for the reference-provenance assessment.
  *
  * A UI-fidelity reference is a PNG; the gate cannot read its text. So validity
  * is asserted at export time as provenance metadata, and the gate checks the
- * METADATA, never the pixels (no OCR). A reference that is absent, unprovenanced,
- * placeholder-bearing (`resolved == false`), or in the wrong locale is
- * UNVERIFIABLE — a loud, mechanical verdict, not a confident-but-false PASS.
+ * METADATA, never the pixels (no OCR).
  *
- * Content differences (copy wording, geometry) are NOT checked here — those are
- * soft, judged findings that legitimately drift between export and run.
+ * The assessment splits into two severities:
+ *  - FATAL faults (reference absent; no provenance while a render locale is
+ *    declared): the screen cannot be judged at all → status `unverifiable`.
+ *  - COPY-CHANNEL downgrades (unresolved placeholders, locale mismatch): the
+ *    screen renders and is judged on every non-copy channel; copy comparisons
+ *    are skipped and reported as a `copy_unverifiable` advisory. Placeholder
+ *    copy in a design is normal customer reality — the product adapts, the
+ *    customer is never told to re-export.
+ *
+ * The check arms whenever provenance is present; a declared render locale is
+ * only required for the locale comparison itself (and preserves the legacy
+ * NO_PROVENANCE behaviour for unprovenanced screens).
  */
 export {};
 //# sourceMappingURL=fidelity-reference-provenance.test.d.ts.map

package/dist/src/yaml/steps/fidelity-reference-provenance.test.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"fidelity-reference-provenance.test.d.ts","sourceRoot":"","sources":["../../../../src/yaml/steps/fidelity-reference-provenance.test.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;GAWG"}
+{"version":3,"file":"fidelity-reference-provenance.test.d.ts","sourceRoot":"","sources":["../../../../src/yaml/steps/fidelity-reference-provenance.test.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;;;GAmBG"}

package/dist/src/yaml/steps/fidelity-reference-provenance.test.js

@@ -1,52 +1,116 @@
 /**
- * Unit tests for the reference-provenance gate.
+ * Unit tests for the reference-provenance assessment.
  *
  * A UI-fidelity reference is a PNG; the gate cannot read its text. So validity
  * is asserted at export time as provenance metadata, and the gate checks the
- * METADATA, never the pixels (no OCR). A reference that is absent, unprovenanced,
- * placeholder-bearing (`resolved == false`), or in the wrong locale is
- * UNVERIFIABLE — a loud, mechanical verdict, not a confident-but-false PASS.
+ * METADATA, never the pixels (no OCR).
  *
- * Content differences (copy wording, geometry) are NOT checked here — those are
- * soft, judged findings that legitimately drift between export and run.
+ * The assessment splits into two severities:
+ *  - FATAL faults (reference absent; no provenance while a render locale is
+ *    declared): the screen cannot be judged at all → status `unverifiable`.
+ *  - COPY-CHANNEL downgrades (unresolved placeholders, locale mismatch): the
+ *    screen renders and is judged on every non-copy channel; copy comparisons
+ *    are skipped and reported as a `copy_unverifiable` advisory. Placeholder
+ *    copy in a design is normal customer reality — the product adapts, the
+ *    customer is never told to re-export.
+ *
+ * The check arms whenever provenance is present; a declared render locale is
+ * only required for the locale comparison itself (and preserves the legacy
+ * NO_PROVENANCE behaviour for unprovenanced screens).
  */
 import { describe, test, expect } from '@jest/globals';
-import { provenanceFault, UNVERIFIABLE_STATUS, } from './fidelity-reference-provenance.js';
+import { assessReferenceProvenance, hasReferenceProvenance, UNVERIFIABLE_STATUS, COPY_UNVERIFIABLE_CODE, } from './fidelity-reference-provenance.js';
 const GOOD = {
     figmaNode: '12:345',
     locale: 'en',
     resolved: true,
     exportedAt: '2026-06-18T10:00:00Z',
 };
-describe('provenanceFault', () => {
-    test('a present, provenanced, resolved, locale-matching reference is verifiable', () => {
-        expect(provenanceFault('Guest', GOOD, 'en', true)).toBeNull();
+describe('assessReferenceProvenance', () => {
+    test('a present, provenanced, resolved, locale-matching reference is clean', () => {
+        expect(assessReferenceProvenance('Guest', GOOD, 'en', true)).toEqual({
+            fault: null,
+            copyAdvisory: null,
+        });
     });
-    test('an absent reference is UNVERIFIABLE (REFERENCE_ABSENT)', () => {
-        const fault = provenanceFault('Guest', GOOD, 'en', false);
-        expect(fault?.code).toBe('REFERENCE_ABSENT');
+    test('provenance present without a declared render locale is clean too', () => {
+        expect(assessReferenceProvenance('Guest', GOOD, null, true)).toEqual({
+            fault: null,
+            copyAdvisory: null,
+        });
     });
-    test('a reference with no provenance is UNVERIFIABLE (NO_PROVENANCE)', () => {
-        expect(provenanceFault('Guest', null, 'en', true)?.code).toBe('NO_PROVENANCE');
-        expect(provenanceFault('Guest', undefined, 'en', true)?.code).toBe('NO_PROVENANCE');
+    test('an absent reference with provenance is FATAL (REFERENCE_ABSENT), locale or not', () => {
+        expect(assessReferenceProvenance('Guest', GOOD, 'en', false).fault?.code).toBe('REFERENCE_ABSENT');
+        expect(assessReferenceProvenance('Guest', GOOD, null, false).fault?.code).toBe('REFERENCE_ABSENT');
     });
-    test('incomplete provenance (missing locale/resolved) is UNVERIFIABLE (NO_PROVENANCE)', () => {
-        expect(provenanceFault('Guest', { figmaNode: 'x', exportedAt: 'y' }, 'en', true)?.code).toBe('NO_PROVENANCE');
+    test('unresolved placeholders downgrade the copy channel — never the screen', () => {
+        const assessment = assessReferenceProvenance('Guest', { ...GOOD, resolved: false }, 'en', true);
+        expect(assessment.fault).toBeNull();
+        expect(assessment.copyAdvisory?.code).toBe(COPY_UNVERIFIABLE_CODE);
+        expect(assessment.copyAdvisory?.reason).toBe('unresolved_placeholders');
     });
-    test('a placeholder reference (resolved=false) is UNVERIFIABLE (UNRESOLVED_REFERENCE)', () => {
-        const fault = provenanceFault('Guest', { ...GOOD, resolved: false }, 'en', true);
-        expect(fault?.code).toBe('UNRESOLVED_REFERENCE');
+    test('unresolved placeholders downgrade identically without a render locale', () => {
+        // Live evidence: the same resolved:false reference must earn the same
+        // verdict whether or not the run declared render_locale.
+        const assessment = assessReferenceProvenance('Guest', { ...GOOD, resolved: false }, null, true);
+        expect(assessment.fault).toBeNull();
+        expect(assessment.copyAdvisory?.reason).toBe('unresolved_placeholders');
     });
-    test('a wrong-locale reference is UNVERIFIABLE (LOCALE_MISMATCH)', () => {
+    test('a wrong-locale reference downgrades the copy channel (LOCALE reason)', () => {
         // Italian reference vs an English render.
-        const fault = provenanceFault('Guest', { ...GOOD, locale: 'it' }, 'en', true);
-        expect(fault?.code).toBe('LOCALE_MISMATCH');
+        const assessment = assessReferenceProvenance('Guest', { ...GOOD, locale: 'it' }, 'en', true);
+        expect(assessment.fault).toBeNull();
+        expect(assessment.copyAdvisory?.code).toBe(COPY_UNVERIFIABLE_CODE);
+        expect(assessment.copyAdvisory?.reason).toBe('locale_mismatch');
+    });
+    test('locale comparison requires a declared render locale — its absence skips only that', () => {
+        const assessment = assessReferenceProvenance('Guest', { ...GOOD, locale: 'it' }, null, true);
+        expect(assessment).toEqual({ fault: null, copyAdvisory: null });
+    });
+    test('an absent reference wins over a copy downgrade (nothing to judge against)', () => {
+        const assessment = assessReferenceProvenance('Guest', { ...GOOD, resolved: false }, 'en', false);
+        expect(assessment.fault?.code).toBe('REFERENCE_ABSENT');
+        expect(assessment.copyAdvisory).toBeNull();
+    });
+    test('no provenance with a declared render locale stays FATAL (NO_PROVENANCE, legacy arming)', () => {
+        expect(assessReferenceProvenance('Guest', null, 'en', true).fault?.code).toBe('NO_PROVENANCE');
+        expect(assessReferenceProvenance('Guest', undefined, 'en', true).fault?.code).toBe('NO_PROVENANCE');
+    });
+    test('incomplete provenance (missing locale/resolved) is treated as no provenance', () => {
+        expect(assessReferenceProvenance('Guest', { figmaNode: 'x', exportedAt: 'y' }, 'en', true).fault
+            ?.code).toBe('NO_PROVENANCE');
     });
-    test('every fault carries the screen name and a human reason', () => {
-        const fault = provenanceFault('LoggedIn', { ...GOOD, resolved: false }, 'en', true);
-        expect(fault?.message).toContain('LoggedIn');
-        expect(fault?.message.length).toBeGreaterThan(10);
+    test('no provenance and no render locale is unarmed — the caller keeps legacy behaviour', () => {
+        expect(assessReferenceProvenance('Guest', null, null, false)).toEqual({
+            fault: null,
+            copyAdvisory: null,
+        });
+        expect(assessReferenceProvenance('Guest', null, null, true)).toEqual({
+            fault: null,
+            copyAdvisory: null,
+        });
     });
+    test('faults and advisories carry the screen name and a human reason', () => {
+        const fatal = assessReferenceProvenance('LoggedIn', GOOD, 'en', false);
+        expect(fatal.fault?.message).toContain('LoggedIn');
+        const downgraded = assessReferenceProvenance('LoggedIn', { ...GOOD, resolved: false }, 'en', true);
+        expect(downgraded.copyAdvisory?.message).toContain('LoggedIn');
+        expect(downgraded.copyAdvisory.message.length).toBeGreaterThan(10);
+    });
+    test('the downgrade message never tells the customer to fix their design', () => {
+        const assessment = assessReferenceProvenance('Guest', { ...GOOD, resolved: false }, 'en', true);
+        expect(assessment.copyAdvisory?.message.toLowerCase()).not.toContain('export it');
+    });
+});
+describe('hasReferenceProvenance', () => {
+    test('full export-path provenance is present; partial or missing is not', () => {
+        expect(hasReferenceProvenance(GOOD)).toBe(true);
+        expect(hasReferenceProvenance(null)).toBe(false);
+        expect(hasReferenceProvenance(undefined)).toBe(false);
+        expect(hasReferenceProvenance({ figmaNode: 'x' })).toBe(false);
+    });
+});
+describe('status strings', () => {
     test('exposes the unverifiable status string the result document uses', () => {
         expect(UNVERIFIABLE_STATUS).toBe('unverifiable');
     });

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