@usefragments/core 1.2.0 → 1.3.0

package/dist/index.js

@@ -109,7 +109,7 @@ import {
   ownedImportsEqual,
   resolveComponentGovernance,
   scaleGovernanceRecordSchema
-} from "./chunk-DBVTSUMT.js";
+} from "./chunk-MLRDNSSA.js";
 import {
   AGENT_FORMAT_SCHEMA_VERSION,
   agentErrorEnvelopeSchema,
@@ -134,7 +134,7 @@ import {
   suppressionDirectiveSchema,
   validatorResultSchema,
   violationSchema
-} from "./chunk-BQQTMGLA.js";
+} from "./chunk-57QDBEHQ.js";
 import {
   OWNED_PACKAGE_IDENTITY_EPOCH,
   OWNED_PACKAGE_IDENTITY_SOURCE_SHA256,
@@ -238,6 +238,18 @@ var DEFAULTS = {
   port: 6006
 };
 
+// src/evidence.ts
+var EVIDENCE_ORDER = [
+  "none",
+  "runtime_advisory",
+  "provenance_bound",
+  "source_backed",
+  "receipt_backed"
+];
+function canBlock(grade) {
+  return EVIDENCE_ORDER.indexOf(grade) >= EVIDENCE_ORDER.indexOf("source_backed");
+}
+
 // src/conform-prove.ts
 var PROVE_MAX_PASSES = 8;
 var PROVE_DEFAULT_MAX_PASSES = 4;
@@ -386,6 +398,7 @@ async function proveCompliant(input, callbacks, options = {}) {
 
 // src/agent-format.ts
 function buildAgentFormat(input) {
+  const zeroRulesLoaded = input.integrity.rulesLoaded === 0;
   const integrityFailed = !input.integrity.healthy || input.integrity.inert;
   const score = integrityFailed ? 0 : scoreFindings(input.findings);
   const visibleFindings = uniqueFindings(input.findings).slice(0, input.maxFindings ?? 50);
@@ -398,15 +411,14 @@ function buildAgentFormat(input) {
     severity: finding.severity,
     level: severityLevel(finding.severity),
     message: finding.message,
+    evidenceGrade: finding.evidenceGrade,
     evidence: input.includeEvidence ? finding.evidence : [],
     plan: planForFinding(finding)
   }));
   const hasErrors = input.findings.some((finding) => severityLevel(finding.severity) === "error");
-  return {
+  const shared = {
     schemaVersion: AGENT_FORMAT_SCHEMA_VERSION,
-    passed: !integrityFailed && (input.passed ?? true) && !hasErrors,
-    score,
-    summary: integrityFailed ? `failed with score ${score}; ${input.integrity.reasons.join("; ") || "governance integrity is unhealthy"}` : agentSummary(input.findings.length, input.filesScanned, score),
+    summary: zeroRulesLoaded ? "indeterminate; zero_rules_loaded" : integrityFailed ? `failed with score ${score}; ${input.integrity.reasons.join("; ") || "governance integrity is unhealthy"}` : agentSummary(input.findings.length, input.filesScanned, score),
     integrity: input.integrity,
     fix_first: agentFindings.filter((finding) => finding.plan.confidence >= 0.8),
     remaining: agentFindings.filter((finding) => finding.plan.confidence < 0.8),
@@ -428,7 +440,23 @@ function buildAgentFormat(input) {
         ...suppression.expiresOn ? { expiresOn: suppression.expiresOn } : {},
         scope: "line"
       }))
-    } : {}
+    } : {},
+    ...input.provenance ? { provenance: input.provenance } : {},
+    ...input.verdict ? { verdict: input.verdict } : {}
+  };
+  if (zeroRulesLoaded) {
+    return {
+      ...shared,
+      integrity: { ...input.integrity, rulesLoaded: 0 },
+      passed: false,
+      status: "indeterminate",
+      reasons: ["zero_rules_loaded"]
+    };
+  }
+  return {
+    ...shared,
+    passed: !integrityFailed && (input.passed ?? true) && !hasErrors,
+    score
   };
 }
 function uniqueFindings(findings) {
@@ -3326,19 +3354,35 @@ function parsedOutputToDesignTokens(output, filePath) {
   return tokens;
 }
 function scssOutputToDesignTokens(output, filePath) {
-  const names = /* @__PURE__ */ new Set();
-  const tokens = [];
+  const tokensByName = /* @__PURE__ */ new Map();
   for (const cat of Object.values(output.categories)) {
     for (const t of cat) {
-      const cssName = t.name.startsWith("$") ? `--${t.name.slice(1)}` : t.name;
-      if (!cssName.startsWith("--") || names.has(cssName)) continue;
-      names.add(cssName);
-      tokens.push(designTokenFromParsed(cssName, t, filePath));
+      const isScssVariable = t.name.startsWith("$");
+      const cssName = isScssVariable ? `--${t.name.slice(1)}` : t.name;
+      if (!cssName.startsWith("--")) continue;
+      const existing = tokensByName.get(cssName);
+      if (!existing) {
+        tokensByName.set(cssName, {
+          parsed: t,
+          referenceFormat: isScssVariable ? "scss-var" : "css-var",
+          sourceNames: /* @__PURE__ */ new Set([t.name])
+        });
+      } else {
+        existing.sourceNames.add(t.name);
+        if (isScssVariable) {
+          existing.parsed = t;
+          existing.referenceFormat = "scss-var";
+        }
+      }
     }
   }
-  return tokens;
+  return [...tokensByName].map(
+    ([name, token]) => designTokenFromParsed(name, token.parsed, filePath, token.referenceFormat, [
+      ...token.sourceNames
+    ])
+  );
 }
-function designTokenFromParsed(name, parsed, filePath) {
+function designTokenFromParsed(name, parsed, filePath, referenceFormat, sourceNames) {
   return {
     name,
     rawValue: parsed.value ?? "",
@@ -3351,6 +3395,8 @@ function designTokenFromParsed(name, parsed, filePath) {
     level: 1,
     referenceChain: [],
     sourceFile: filePath,
+    referenceFormat,
+    ...sourceNames?.length ? { sourceNames } : {},
     theme: "default",
     selector: ":root",
     description: parsed.description
@@ -4289,12 +4335,37 @@ function makeFinding(input) {
     fingerprint,
     location: input.location,
     evidence: input.evidence,
+    evidenceGrade: input.evidenceGrade ?? "source_backed",
     fix: input.fix,
     attributes: input.attributes
   });
 }
 
 // src/rules/utils.ts
+function emitFix(fix, proof, ix) {
+  const reasons = [];
+  if (proof.editKind !== fix.kind) reasons.push("edit kind does not match proof");
+  if (!proof.valuePreserving) reasons.push("value-preservation proof missing");
+  if (proof.symbols.length === 0) reasons.push("token-symbol proof missing");
+  const missingSymbols = proof.symbols.filter((symbol) => !ix.tokens.symbolExists(symbol));
+  if (missingSymbols.length > 0) {
+    reasons.push(`absent token symbol: ${missingSymbols.join(", ")}`);
+  }
+  const inapplicableSymbols = proof.symbols.filter((symbol) => {
+    const definition = ix.tokens.definitionForSymbol(symbol);
+    return definition !== void 0 && !isApplicableTokenReference(definition.referenceFormat);
+  });
+  if (inapplicableSymbols.length > 0) {
+    reasons.push(`token reference is not directly applicable: ${inapplicableSymbols.join(", ")}`);
+  }
+  return {
+    fix: { ...fix, deterministic: reasons.length === 0 },
+    ...reasons.length > 0 ? { downgradeReason: reasons.join("; ") } : {}
+  };
+}
+function tokenSymbolsInText(value) {
+  return [...new Set(value.match(/\$[A-Za-z0-9_-]+|--[A-Za-z0-9_-]+/g) ?? [])];
+}
 function indexPropsByNodeId(ix) {
   const out = /* @__PURE__ */ new Map();
   for (const fact of ix.byKind("usage_prop_resolved")) {
@@ -4373,13 +4444,6 @@ function readUsageNode(ix, id) {
   const fact = ix.get(id);
   return fact && fact.kind === "usage_node" ? fact : void 0;
 }
-function cssVariableNames(tokens) {
-  const names = /* @__PURE__ */ new Set();
-  for (const token of tokens) {
-    names.add(token.name.startsWith("--") ? token.name : `--${token.name}`);
-  }
-  return names;
-}
 function contractPrefixFamilies(names) {
   const families = /* @__PURE__ */ new Set();
   for (const name of names) {
@@ -6170,6 +6234,7 @@ function ruleStylesNoRawColor(ix) {
     if (!color) continue;
     if (isExemptColor(color, policy.except)) continue;
     const resolution = resolveColorToken(decl.property, color, colorTokens);
+    const fixEmission = resolution?.kind === "exact" ? buildTokenFix(decl.property, decl.value, color, resolution, ix) : void 0;
     const evidenceIds = resolution ? [decl.id, policy.id, resolution.token.id] : [decl.id, policy.id];
     findings.push(
       makeFinding({
@@ -6187,14 +6252,15 @@ function ruleStylesNoRawColor(ix) {
           property: decl.property,
           value: color
         },
-        fix: resolution?.kind === "exact" ? buildTokenFix(decl.property, decl.value, color, resolution) : void 0,
+        fix: fixEmission?.fix,
         attributes: {
           property: decl.property,
           rawValue: decl.value,
           color,
           source: "css",
           suggestedToken: resolution?.token.name,
-          ...resolution ? { tokenMatch: resolution.kind } : {}
+          ...resolution ? { tokenMatch: resolution.kind } : {},
+          ...fixEmission?.downgradeReason ? { downgradeReason: fixEmission.downgradeReason } : {}
         }
       })
     );
@@ -6209,6 +6275,7 @@ function ruleStylesNoRawColor(ix) {
     if (!node) continue;
     const componentEvidenceId = componentByNode.get(node.id)?.id;
     const resolution = resolveColorToken(inline.property, color, colorTokens);
+    const fixEmission = resolution?.kind === "exact" ? buildTokenFix(inline.property, inline.value, color, resolution, ix) : void 0;
     const baseEvidence = componentEvidenceId ? [node.id, componentEvidenceId, inline.id, policy.id] : [node.id, inline.id, policy.id];
     const evidenceIds = resolution ? [...baseEvidence, resolution.token.id] : baseEvidence;
     findings.push(
@@ -6227,14 +6294,15 @@ function ruleStylesNoRawColor(ix) {
           property: inline.property,
           value: color
         },
-        fix: resolution?.kind === "exact" ? buildTokenFix(inline.property, inline.value, color, resolution) : void 0,
+        fix: fixEmission?.fix,
         attributes: {
           property: inline.property,
           rawValue: inline.value,
           color,
           source: "jsx",
           suggestedToken: resolution?.token.name,
-          ...resolution ? { tokenMatch: resolution.kind } : {}
+          ...resolution ? { tokenMatch: resolution.kind } : {},
+          ...fixEmission?.downgradeReason ? { downgradeReason: fixEmission.downgradeReason } : {}
         }
       })
     );
@@ -6318,21 +6386,24 @@ function normalizeColor2(value) {
   }
   return lower;
 }
-function buildTokenFix(property, rawValue, rawColor, match) {
+function buildTokenFix(property, rawValue, rawColor, match, ix) {
   const reference = tokenReference(match.token.name);
   const value = replaceRawColor(rawValue, rawColor, reference);
-  return {
-    kind: "replaceStyleValue",
-    title: `Replace ${property} with ${value}`,
-    property,
-    value,
-    // Apply automatically only when the swap is unambiguous AND the reference
-    // resolves verbatim. An ambiguous match (several tokens share the value,
-    // none role-matching) or a token that can't be referenced from CSS (a Sass
-    // *map* member, or a DTCG JSON token with no emitted custom property) is a
-    // suggestion — applying it would cross roles or write non-compiling code.
-    deterministic: !match.ambiguous && isApplicableTokenReference(match.token.referenceFormat)
-  };
+  return emitFix(
+    {
+      kind: "replaceStyleValue",
+      title: `Replace ${property} with ${value}`,
+      property,
+      value,
+      deterministic: true
+    },
+    {
+      symbols: [match.token.name],
+      editKind: "replaceStyleValue",
+      valuePreserving: !match.ambiguous
+    },
+    ix
+  );
 }
 function replaceRawColor(rawValue, rawColor, replacement) {
   if (rawValue === rawColor) return replacement;
@@ -6363,6 +6434,7 @@ function ruleStylesNoRawDimensions(ix) {
     if (!resolution) continue;
     const tokenIds = resolutionTokenIds(resolution);
     const evidenceIds = tokenIds.length ? [decl.id, policy.id, ...tokenIds] : [decl.id, policy.id];
+    const fixEmission = dimensionFix(decl.property, resolution, ix);
     findings.push(
       makeFinding({
         ruleId: RULE_ID9,
@@ -6379,12 +6451,13 @@ function ruleStylesNoRawDimensions(ix) {
           property: decl.property,
           value: decl.value
         },
-        fix: dimensionFix(decl.property, resolution),
+        fix: fixEmission?.fix,
         attributes: {
           property: decl.property,
           rawValue: decl.value,
           source: "css",
-          suggestedToken: resolutionSuggestedToken(resolution)
+          suggestedToken: resolutionSuggestedToken(resolution),
+          ...fixEmission?.downgradeReason ? { downgradeReason: fixEmission.downgradeReason } : {}
         }
       })
     );
@@ -6403,6 +6476,7 @@ function ruleStylesNoRawDimensions(ix) {
     const baseEvidence = componentEvidenceId ? [node.id, componentEvidenceId, inline.id, policy.id] : [node.id, inline.id, policy.id];
     const tokenIds = resolutionTokenIds(resolution);
     const evidenceIds = tokenIds.length ? [...baseEvidence, ...tokenIds] : baseEvidence;
+    const fixEmission = dimensionFix(inline.property, resolution, ix);
     findings.push(
       makeFinding({
         ruleId: RULE_ID9,
@@ -6419,12 +6493,13 @@ function ruleStylesNoRawDimensions(ix) {
           property: inline.property,
           value: inline.value
         },
-        fix: dimensionFix(inline.property, resolution),
+        fix: fixEmission?.fix,
         attributes: {
           property: inline.property,
           rawValue: inline.value,
           source: "jsx",
-          suggestedToken: resolutionSuggestedToken(resolution)
+          suggestedToken: resolutionSuggestedToken(resolution),
+          ...fixEmission?.downgradeReason ? { downgradeReason: fixEmission.downgradeReason } : {}
         }
       })
     );
@@ -6469,15 +6544,23 @@ function dimensionMessage(rawValue, property, preferLabel, resolution, inline) {
   }
   return `Raw dimension ${rawValue} on ${where}. Use a ${preferLabel} instead.`;
 }
-function dimensionFix(property, resolution) {
+function dimensionFix(property, resolution, ix) {
   if (resolution.kind === "exact") {
-    return {
-      kind: "replaceStyleValue",
-      title: `Replace ${property} with ${resolution.fixValue}`,
-      property,
-      value: resolution.fixValue,
-      deterministic: true
-    };
+    return emitFix(
+      {
+        kind: "replaceStyleValue",
+        title: `Replace ${property} with ${resolution.fixValue}`,
+        property,
+        value: resolution.fixValue,
+        deterministic: true
+      },
+      {
+        symbols: resolution.tokens.map((token) => token.name),
+        editKind: "replaceStyleValue",
+        valuePreserving: true
+      },
+      ix
+    );
   }
   return void 0;
 }
@@ -6578,7 +6661,7 @@ function resolveSpacingValue(input) {
   let anyOffScale = false;
   let canFixAll = true;
   let reliableSuggestion = true;
-  let allApplicableValuePreserving = true;
+  let allValuePreserving = true;
   for (const part of parts) {
     const normalized = normalizeLengthForScale(part.parsed, input.scale);
     if (normalized === null) return null;
@@ -6592,8 +6675,7 @@ function resolveSpacingValue(input) {
       }
       anyViolation = true;
       const reference = tokenReference(exactToken.name);
-      const applicable = isApplicableTokenReference(exactToken.referenceFormat) && normalized.deterministicFix;
-      if (!applicable) allApplicableValuePreserving = false;
+      if (!normalized.deterministicFix) allValuePreserving = false;
       suggestedParts.push(reference);
       if (!firstViolation) {
         firstViolation = {
@@ -6601,7 +6683,7 @@ function resolveSpacingValue(input) {
           suggestedValue: reference,
           suggestedToken: exactToken.name,
           fixEmittable: true,
-          deterministicFix: applicable,
+          deterministicFix: normalized.deterministicFix,
           reason: "token-equivalent",
           matchedToken: exactToken.name,
           assumedRootFontSizePx: normalized.assumedRootFontSizePx,
@@ -6612,7 +6694,7 @@ function resolveSpacingValue(input) {
     }
     anyViolation = true;
     anyOffScale = true;
-    allApplicableValuePreserving = false;
+    allValuePreserving = false;
     const nearest = nearestSignedScaleValue(normalized.value, input.allowed);
     const snapsToZero = nearest === 0 && normalized.value !== 0;
     let suggestedPart;
@@ -6645,7 +6727,7 @@ function resolveSpacingValue(input) {
   const joined = suggestedParts.join(" ");
   const changes = joined !== input.raw.trim().replace(/\s+/g, " ");
   const fixEmittable = canFixAll && reliableSuggestion && changes;
-  const deterministic = fixEmittable && !anyOffScale && allApplicableValuePreserving;
+  const deterministic = fixEmittable && !anyOffScale && allValuePreserving;
   return {
     ...firstViolation,
     reason: anyOffScale ? "off-scale" : "token-equivalent",
@@ -6709,6 +6791,7 @@ function checkDeclaration(ix, decl, lookupFor) {
     tokens: lookupFor(scale)
   });
   if (!checked) return null;
+  const fixEmission = buildSpacingFix(decl.property, checked, ix);
   return makeFinding({
     ruleId: RULE_ID10,
     ruleVersion: RULE_VERSION11,
@@ -6724,7 +6807,7 @@ function checkDeclaration(ix, decl, lookupFor) {
       property: decl.property,
       value: decl.value
     },
-    fix: buildSpacingFix(decl.property, checked),
+    fix: fixEmission?.fix,
     attributes: {
       property: decl.property,
       rawValue: decl.value,
@@ -6738,7 +6821,8 @@ function checkDeclaration(ix, decl, lookupFor) {
       normalizedUnit: scale.unit,
       assumedRootFontSizePx: checked.assumedRootFontSizePx,
       assumedEmBasePx: checked.assumedEmBasePx,
-      source: "css"
+      source: "css",
+      ...fixEmission?.downgradeReason ? { downgradeReason: fixEmission.downgradeReason } : {}
     }
   });
 }
@@ -6758,6 +6842,7 @@ function checkInlineStyle(ix, inline, componentByNode, lookupFor) {
     bareNumberFix: inline.valueKind === "number"
   });
   if (!checked) return null;
+  const fixEmission = buildSpacingFix(inline.property, checked, ix);
   const node = readUsageNode(ix, inline.nodeId);
   if (!node) return null;
   const componentEvidenceId = componentByNode.get(node.id)?.id;
@@ -6777,7 +6862,7 @@ function checkInlineStyle(ix, inline, componentByNode, lookupFor) {
       property: inline.property,
       value: inline.value
     },
-    fix: buildSpacingFix(inline.property, checked),
+    fix: fixEmission?.fix,
     attributes: {
       property: inline.property,
       rawValue: inline.value,
@@ -6791,19 +6876,28 @@ function checkInlineStyle(ix, inline, componentByNode, lookupFor) {
       normalizedUnit: scale.unit,
       assumedRootFontSizePx: checked.assumedRootFontSizePx,
       assumedEmBasePx: checked.assumedEmBasePx,
-      source: "jsx"
+      source: "jsx",
+      ...fixEmission?.downgradeReason ? { downgradeReason: fixEmission.downgradeReason } : {}
     }
   });
 }
-function buildSpacingFix(property, checked) {
+function buildSpacingFix(property, checked, ix) {
   if (!checked.fixEmittable || checked.suggestedValue === void 0) return void 0;
-  return {
-    kind: "replaceStyleValue",
-    title: `Replace ${property} with ${checked.suggestedValue}`,
-    property,
-    value: checked.suggestedValue,
-    deterministic: checked.deterministicFix
-  };
+  return emitFix(
+    {
+      kind: "replaceStyleValue",
+      title: `Replace ${property} with ${checked.suggestedValue}`,
+      property,
+      value: checked.suggestedValue,
+      deterministic: true
+    },
+    {
+      symbols: tokenSymbolsInText(checked.suggestedValue),
+      editKind: "replaceStyleValue",
+      valuePreserving: checked.deterministicFix
+    },
+    ix
+  );
 }
 function spacingMessage(property, value, allowed, unit, checked) {
   if (checked.reason === "token-equivalent" && checked.matchedToken) {
@@ -6832,6 +6926,7 @@ function ruleStylesNoRawTypography(ix) {
     if (decl.property.toLowerCase() !== "font-size") continue;
     const checked = checkFontSize(decl.value, allowed, scale, tokens);
     if (!checked) continue;
+    const fixEmission = buildFix(decl.property, checked, ix);
     findings.push(
       makeFinding({
         ruleId: RULE_ID11,
@@ -6848,7 +6943,7 @@ function ruleStylesNoRawTypography(ix) {
           property: decl.property,
           value: decl.value
         },
-        fix: buildFix(decl.property, checked),
+        fix: fixEmission?.fix,
         attributes: {
           property: decl.property,
           rawValue: decl.value,
@@ -6856,7 +6951,8 @@ function ruleStylesNoRawTypography(ix) {
           allowed,
           suggestedValue: checked.suggestedValue,
           matchedToken: checked.matchedToken,
-          source: "css"
+          source: "css",
+          ...fixEmission?.downgradeReason ? { downgradeReason: fixEmission.downgradeReason } : {}
         }
       })
     );
@@ -6865,8 +6961,15 @@ function ruleStylesNoRawTypography(ix) {
   for (const inline of ix.byKind("usage_inline_style")) {
     if (inline.valueKind === "css-variable") continue;
     if (!FONT_SIZE_PROPERTIES.has(inline.property.toLowerCase())) continue;
-    const checked = checkFontSize(inline.value, allowed, scale, tokens, inline.valueKind === "number");
+    const checked = checkFontSize(
+      inline.value,
+      allowed,
+      scale,
+      tokens,
+      inline.valueKind === "number"
+    );
     if (!checked) continue;
+    const fixEmission = buildFix(inline.property, checked, ix);
     const node = readUsageNode(ix, inline.nodeId);
     if (!node) continue;
     const componentEvidenceId = componentByNode.get(node.id)?.id;
@@ -6887,7 +6990,7 @@ function ruleStylesNoRawTypography(ix) {
           property: inline.property,
           value: inline.value
         },
-        fix: buildFix(inline.property, checked),
+        fix: fixEmission?.fix,
         attributes: {
           property: inline.property,
           rawValue: inline.value,
@@ -6895,7 +6998,8 @@ function ruleStylesNoRawTypography(ix) {
           allowed,
           suggestedValue: checked.suggestedValue,
           matchedToken: checked.matchedToken,
-          source: "jsx"
+          source: "jsx",
+          ...fixEmission?.downgradeReason ? { downgradeReason: fixEmission.downgradeReason } : {}
         }
       })
     );
@@ -6925,11 +7029,10 @@ function checkFontSize(raw, allowed, scale, tokens, bareNumberFix = false) {
   const exactToken = tokens.get(magnitude);
   if (matchesScale(normalized.value, allowed)) {
     if (!exactToken) return null;
-    const applicable = isApplicableTokenReference(exactToken.referenceFormat) && normalized.deterministicFix;
     return {
       suggestedValue: tokenReference(exactToken.name),
       fixEmittable: true,
-      deterministicFix: applicable,
+      deterministicFix: normalized.deterministicFix,
       reason: "token-equivalent",
       matchedToken: exactToken.name
     };
@@ -6947,15 +7050,23 @@ function checkFontSize(raw, allowed, scale, tokens, bareNumberFix = false) {
     reason: "off-scale"
   };
 }
-function buildFix(property, checked) {
+function buildFix(property, checked, ix) {
   if (!checked.fixEmittable || checked.suggestedValue === void 0) return void 0;
-  return {
-    kind: "replaceStyleValue",
-    title: `Replace ${property} with ${checked.suggestedValue}`,
-    property,
-    value: checked.suggestedValue,
-    deterministic: checked.deterministicFix
-  };
+  return emitFix(
+    {
+      kind: "replaceStyleValue",
+      title: `Replace ${property} with ${checked.suggestedValue}`,
+      property,
+      value: checked.suggestedValue,
+      deterministic: true
+    },
+    {
+      symbols: tokenSymbolsInText(checked.suggestedValue),
+      editKind: "replaceStyleValue",
+      valuePreserving: checked.deterministicFix
+    },
+    ix
+  );
 }
 function typographyMessage(property, value, allowed, unit, checked) {
   if (checked.reason === "token-equivalent" && checked.matchedToken) {
@@ -7629,7 +7740,7 @@ var SASS_FILE = /\.(scss|sass)$/i;
 function ruleTokensRequireDualFallback(ix) {
   const policy = ix.policy.ruleConfig(RULE_ID19);
   if (!policy?.enabled) return [];
-  const knownTokenVars = cssVariableNames(ix.tokens.list());
+  const tokensByCssVariable = indexTokensByCssVariable(ix.tokens.list());
   const findings = [];
   for (const decl of ix.byKind("style_declaration")) {
     if (!SASS_FILE.test(decl.file)) continue;
@@ -7639,19 +7750,35 @@ function ruleTokensRequireDualFallback(ix) {
       const tokenName = match[1];
       const hasFallback = match[2] !== void 0;
       if (hasFallback) continue;
-      if (!knownTokenVars.has(tokenName) && !tokenName.startsWith("--fui-")) continue;
+      const token = tokensByCssVariable.get(tokenName);
+      if (!token) continue;
       const rawValue = match[0];
       const scssVar = tokenName.replace(/^--/, "$");
-      const replacement = `var(${tokenName}, ${scssVar})`;
-      const nextValue = decl.value.replace(rawValue, replacement);
+      const hasScssVariable = token.referenceFormat === "scss-var";
+      const nextValue = hasScssVariable ? decl.value.replace(rawValue, `var(${tokenName}, ${scssVar})`) : void 0;
+      const fixEmission = nextValue ? emitFix(
+        {
+          kind: "replaceStyleValue",
+          title: `Add fallback for ${tokenName}`,
+          property: decl.property,
+          value: nextValue,
+          deterministic: true
+        },
+        {
+          symbols: [tokenName, scssVar],
+          editKind: "replaceStyleValue",
+          valuePreserving: true
+        },
+        ix
+      ) : void 0;
       findings.push(
         makeFinding({
           ruleId: RULE_ID19,
           ruleVersion: RULE_VERSION20,
           severity: policy.severity ?? "warn",
-          message: `var(${tokenName}) is missing an SCSS fallback. Use var(${tokenName}, ${scssVar}).`,
+          message: hasScssVariable ? `var(${tokenName}) is missing an SCSS fallback. Use var(${tokenName}, ${scssVar}).` : `var(${tokenName}) is missing a fallback. No matching SCSS variable was found in the token source; add a fallback manually or define ${scssVar}.`,
           location: decl.location,
-          evidence: ix.evidence([decl.id, policy.id]),
+          evidence: ix.evidence([decl.id, token.id, policy.id]),
           fingerprintIdentity: {
             file: decl.file,
             selector: decl.selector,
@@ -7659,18 +7786,13 @@ function ruleTokensRequireDualFallback(ix) {
             property: decl.property,
             tokenName
           },
-          fix: {
-            kind: "replaceStyleValue",
-            title: `Add fallback for ${tokenName}`,
-            property: decl.property,
-            value: nextValue,
-            deterministic: true
-          },
+          fix: fixEmission?.fix,
           attributes: {
             property: decl.property,
             rawValue: decl.value,
             tokenName,
-            suggestedValue: nextValue,
+            ...nextValue ? { suggestedValue: nextValue } : {},
+            ...fixEmission?.downgradeReason ? { downgradeReason: fixEmission.downgradeReason } : {},
             source: "css"
           }
         })
@@ -7679,6 +7801,17 @@ function ruleTokensRequireDualFallback(ix) {
   }
   return findings;
 }
+function indexTokensByCssVariable(tokens) {
+  const indexed = /* @__PURE__ */ new Map();
+  for (const token of tokens) {
+    const cssVariable = token.name.startsWith("--") ? token.name : token.name.startsWith("$") ? `--${token.name.slice(1)}` : `--${token.name}`;
+    const existing = indexed.get(cssVariable);
+    if (!existing || token.referenceFormat === "scss-var") {
+      indexed.set(cssVariable, token);
+    }
+  }
+  return indexed;
+}
 
 // src/rules/tokens-css-vars-must-be-defined.ts
 var RULE_ID20 = "tokens/css-vars-must-be-defined";
@@ -7770,6 +7903,8 @@ var BLOCKING_RULE_ALLOWLIST = /* @__PURE__ */ new Set([
   // imported component bypasses its canonical
 ]);
 function gatesCi(finding, failOnWarnings) {
+  if (!canBlock(finding.evidenceGrade ?? "source_backed")) return false;
+  if (finding.attributes?.advisory === true) return false;
   const level = severityLevel(finding.severity);
   return level === "error" || failOnWarnings && level === "warn";
 }
@@ -8500,6 +8635,7 @@ export {
   DEFAULTS,
   DEFAULT_ENHANCED_STYLE_PROPERTIES,
   DEFAULT_STYLE_PROPERTIES,
+  EVIDENCE_ORDER,
   EXPLAIN_URL_BASE,
   FRAGMENTS_INTERNAL_RULE_IDS,
   FactIndex,
@@ -8551,6 +8687,7 @@ export {
   byCode,
   byRuleId,
   calculateDeltaE,
+  canBlock,
   canonicalJson,
   canonicalPreimage,
   canonicalizeOwnedComponentId,