@usefragments/core 1.0.0 → 1.3.0

package/dist/index.js

@@ -1,9 +1,9 @@
-import {
-  ComponentGraphEngine
-} from "./chunk-SH4KPIYH.js";
 import {
   generateContext
 } from "./chunk-X34IA4LR.js";
+import {
+  ComponentGraphEngine
+} from "./chunk-SH4KPIYH.js";
 import {
   resolveArea
 } from "./chunk-3LLRNCPX.js";
@@ -109,9 +109,13 @@ import {
   ownedImportsEqual,
   resolveComponentGovernance,
   scaleGovernanceRecordSchema
-} from "./chunk-243QYRUF.js";
+} from "./chunk-MLRDNSSA.js";
 import {
+  AGENT_FORMAT_SCHEMA_VERSION,
+  agentErrorEnvelopeSchema,
   agentFormatSchema,
+  agentIntegritySchema,
+  agentOutputSchema,
   factEvidenceSchema,
   factLocationSchema,
   findingFixSchema,
@@ -130,7 +134,7 @@ import {
   suppressionDirectiveSchema,
   validatorResultSchema,
   violationSchema
-} from "./chunk-R3X7UBHU.js";
+} from "./chunk-57QDBEHQ.js";
 import {
   OWNED_PACKAGE_IDENTITY_EPOCH,
   OWNED_PACKAGE_IDENTITY_SOURCE_SHA256,
@@ -234,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;
@@ -382,7 +398,9 @@ async function proveCompliant(input, callbacks, options = {}) {
 
 // src/agent-format.ts
 function buildAgentFormat(input) {
-  const score = scoreFindings(input.findings);
+  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);
   const agentFindings = visibleFindings.map((finding) => ({
     code: finding.code,
@@ -393,15 +411,15 @@ 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 {
-    schemaVersion: "typestyle.agent.v1",
-    passed: (input.passed ?? true) && !hasErrors,
-    score,
-    summary: agentSummary(input.findings.length, input.filesScanned, score),
+  const shared = {
+    schemaVersion: AGENT_FORMAT_SCHEMA_VERSION,
+    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),
     suppression_template: {
@@ -422,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) {
@@ -3320,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 ?? "",
@@ -3345,6 +3395,8 @@ function designTokenFromParsed(name, parsed, filePath) {
     level: 1,
     referenceChain: [],
     sourceFile: filePath,
+    referenceFormat,
+    ...sourceNames?.length ? { sourceNames } : {},
     theme: "default",
     selector: ":root",
     description: parsed.description
@@ -4283,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")) {
@@ -4367,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) {
@@ -4994,7 +5064,8 @@ function ruleComponentsPreferLibrary(ix) {
     if (node.element.includes(".")) continue;
     const props = propsByNode.get(node.id) ?? [];
     const textChildren = textByNode.get(node.id) ?? [];
-    const imported = importsByFileAndLocal.get(node.file)?.get(node.element);
+    const importsForFile = importsByFileAndLocal.get(node.file);
+    const imported = importsForFile?.get(node.element);
     const nodeInputType = node.element === "input" ? readStaticStringProp(props, "type") : void 0;
     const mapped = findMapping(node, nodeInputType, mappings);
     if (mapped && imported && isMappedCanonicalImport(imported, mapped)) continue;
@@ -5005,9 +5076,11 @@ function ruleComponentsPreferLibrary(ix) {
       const suggestedComponent2 = mapped.name;
       const suggestedImport2 = importPath ?? "the canonical library";
       const propMapping = mapped.propMapping ?? [];
+      const propCompatibility = assessMappedPropCompatibility(props, propMapping);
       const roleMatch = isRoleMatch(node, mapped);
       const precisionTier2 = roleMatch ? "role-reimpl" : "exact-html";
       if (imported && importPath && !ownedImportsEqual(imported.source, importPath) && node.element === suggestedComponent2) {
+        if (!isLocalExactComponentImportRedirectCandidate(imported, suggestedComponent2)) continue;
         const key = `${imported.file}\0${imported.local}\0${imported.source}\0${importPath}`;
         if (seenImportFixes.has(key)) continue;
         seenImportFixes.add(key);
@@ -5015,8 +5088,8 @@ function ruleComponentsPreferLibrary(ix) {
           makeFinding({
             ruleId: RULE_ID2,
             ruleVersion: RULE_VERSION2,
-            severity: policy.severity ?? "warn",
-            message: `<${node.element}> should import from ${importPath}.`,
+            severity: capAdvisorySeverity(policy.severity),
+            message: `<${node.element}> may need to import from ${importPath}; verify that the local component contract is compatible first.`,
             location: imported.location,
             evidence: ix.evidence([node.id, imported.id, policy.id]),
             fingerprintIdentity: {
@@ -5030,14 +5103,16 @@ function ruleComponentsPreferLibrary(ix) {
               title: `Replace import path with "${importPath}"`,
               from: imported.source,
               to: importPath,
-              deterministic: true
+              deterministic: false
             },
             attributes: {
               rawValue: imported.source,
               suggestedComponent: suggestedComponent2,
               suggestedImport: importPath,
               canonical: mapped.canonical,
-              confidence: mapped.confidence
+              confidence: mapped.confidence,
+              advisory: true,
+              contractProof: "missing"
             }
           })
         );
@@ -5067,7 +5142,11 @@ function ruleComponentsPreferLibrary(ix) {
               title: `Replace <${node.element}> with <${suggestedComponent2}>`,
               from: node.element,
               to: suggestedComponent2,
-              deterministic: true
+              // The fact IR cannot prove that it observed every JSX
+              // attribute shape (notably dynamic inline styles). The
+              // conform AST preflight may promote this guided fix only
+              // after it proves the complete prop surface directly.
+              deterministic: false
             }
           } : {},
           attributes: {
@@ -5077,8 +5156,12 @@ function ruleComponentsPreferLibrary(ix) {
             canonical: mapped.canonical,
             confidence: mapped.confidence,
             propMapping,
+            propCompatibility: propCompatibility.complete ? "observed-complete" : "incomplete",
+            ...mapped.conformStatus === "confirmed" ? { canonicalMappingConfirmed: true } : {},
+            ...propCompatibility.unprovenProps.length > 0 ? { unprovenProps: propCompatibility.unprovenProps } : {},
             precisionTier: precisionTier2,
-            ...roleMatch ? { matchedRole: node.role } : {}
+            ...roleMatch ? { matchedRole: node.role } : {},
+            ...isRawHtmlAdvisoryTier(precisionTier2) ? { advisory: true } : {}
           }
         })
       );
@@ -5121,6 +5204,47 @@ function ruleComponentsPreferLibrary(ix) {
     const suggestion = findSuggestionSource(suggestedComponent, sources);
     if (!suggestion) continue;
     if (!builtIn && !shouldSuggest(node, imported)) continue;
+    if (node.element === suggestedComponent) {
+      const importPath = canonicalImportPath(suggestion);
+      if (!imported || !importPath || !isLocalExactComponentImportRedirectCandidate(imported, suggestedComponent)) {
+        continue;
+      }
+      const key = `${imported.file}\0${imported.local}\0${imported.source}\0${importPath}`;
+      if (seenImportFixes.has(key)) continue;
+      seenImportFixes.add(key);
+      findings.push(
+        makeFinding({
+          ruleId: RULE_ID2,
+          ruleVersion: RULE_VERSION2,
+          severity: capAdvisorySeverity(policy.severity),
+          message: `<${node.element}> may need to import from ${importPath}; verify that the local component contract is compatible first.`,
+          location: imported.location,
+          evidence: ix.evidence([node.id, imported.id, policy.id]),
+          fingerprintIdentity: {
+            file: imported.file,
+            local: imported.local,
+            from: imported.source,
+            to: importPath
+          },
+          fix: {
+            kind: "replaceImport",
+            title: `Replace import path with "${importPath}"`,
+            from: imported.source,
+            to: importPath,
+            deterministic: false
+          },
+          attributes: {
+            rawValue: imported.source,
+            suggestedComponent,
+            suggestedImport: importPath,
+            suggestedImportSourceKind: suggestion.kind,
+            advisory: true,
+            contractProof: "missing"
+          }
+        })
+      );
+      continue;
+    }
     if (suggestion.kind === "directory") {
       if (node.element === suggestedComponent) continue;
       if (!builtIn) continue;
@@ -5163,7 +5287,10 @@ function ruleComponentsPreferLibrary(ix) {
             title: `Replace ${rawElement} with <${suggestedComponent}>`,
             from: node.element,
             to: suggestedComponent,
-            deterministic: true
+            // A canonical source proves that the target exists, not that
+            // this native element's complete prop contract is compatible.
+            // Only explicit canonical mappings carry that proof.
+            deterministic: false
           }
         } : {},
         attributes: {
@@ -5172,6 +5299,7 @@ function ruleComponentsPreferLibrary(ix) {
           suggestedImport,
           suggestedImportSourceKind: suggestion.kind,
           precisionTier,
+          propCompatibility: "unknown",
           ...builtIn?.matchedRole ? { matchedRole: builtIn.matchedRole } : {},
           ...builtIn?.inputType ? { matchedInputType: builtIn.inputType } : {},
           ...isRawHtmlAdvisoryTier(precisionTier) ? { advisory: true } : {}
@@ -5288,6 +5416,39 @@ function shouldSuggest(node, imported) {
   if (!/^[A-Z]/.test(node.element)) return false;
   return imported !== void 0;
 }
+function assessMappedPropCompatibility(props, mappings) {
+  const byRawProp = new Map(mappings.map((mapping) => [mapping.rawProp, mapping]));
+  const unprovenProps = props.flatMap((prop) => {
+    if (prop.resolution === "spread") return [prop.prop];
+    const mapping = byRawProp.get(prop.prop);
+    if (!mapping || !mappingCanPreserveProp(mapping, prop)) return [prop.prop];
+    return [];
+  });
+  return { complete: unprovenProps.length === 0, unprovenProps };
+}
+function mappingCanPreserveProp(mapping, prop) {
+  const renames = mapping.rawProp !== mapping.canonicalProp;
+  const valueMap = mapping.valueMap;
+  const translatesValue = valueMap !== void 0 && Object.keys(valueMap).length > 0;
+  if (renames && (!isIdentifier(mapping.rawProp) || !isIdentifier(mapping.canonicalProp))) {
+    return false;
+  }
+  if (!translatesValue) return true;
+  if (!isIdentifier(mapping.rawProp)) return false;
+  return prop.resolution === "static" && typeof prop.value === "string" && Object.prototype.hasOwnProperty.call(valueMap, prop.value);
+}
+function isLocalExactComponentImportRedirectCandidate(usage, componentName) {
+  return isUnaliasedNamedImport(usage, componentName) && isProjectLocalImportSource(usage.source);
+}
+function isUnaliasedNamedImport(usage, componentName) {
+  return isSimpleComponentBinding(usage, componentName) && usage.imported === componentName;
+}
+function isSimpleComponentBinding(usage, componentName) {
+  return usage.namespace !== true && usage.local === componentName;
+}
+function isProjectLocalImportSource(source) {
+  return source.startsWith(".") || source.startsWith("/") || source.startsWith("@/") || source.startsWith("~/");
+}
 function sameHtmlTag(htmlEquivalent, element) {
   return htmlEquivalent !== void 0 && htmlEquivalent.toLowerCase() === element.toLowerCase();
 }
@@ -5320,6 +5481,7 @@ function isCanonicalMappingOption(value) {
   if (record.htmlType !== void 0 && typeof record.htmlType !== "string") return false;
   if (record.importPath !== void 0 && typeof record.importPath !== "string") return false;
   if (record.confidence !== void 0 && typeof record.confidence !== "number") return false;
+  if (record.conformStatus !== void 0 && record.conformStatus !== "confirmed") return false;
   if (record.declaredHtmlEquivalent !== void 0 && typeof record.declaredHtmlEquivalent !== "boolean") {
     return false;
   }
@@ -5422,6 +5584,11 @@ function sourceLabel(source) {
   if (source.kind === "registry") return source.importPath ?? source.installPath;
   return source.path;
 }
+function canonicalImportPath(source) {
+  if (source.kind === "npm") return source.specifier;
+  if (source.kind === "registry") return source.importPath;
+  return void 0;
+}
 function isCanonicalSourceImplementationFile(file, sources) {
   const normalizedFile = normalizePath(file);
   return sources.some((source) => {
@@ -6067,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({
@@ -6084,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 } : {}
         }
       })
     );
@@ -6106,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(
@@ -6124,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 } : {}
         }
       })
     );
@@ -6215,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;
@@ -6260,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,
@@ -6276,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 } : {}
         }
       })
     );
@@ -6300,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,
@@ -6316,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 } : {}
         }
       })
     );
@@ -6366,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;
 }
@@ -6475,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;
@@ -6489,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 = {
@@ -6498,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,
@@ -6509,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;
@@ -6542,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",
@@ -6606,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,
@@ -6621,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,
@@ -6635,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 } : {}
     }
   });
 }
@@ -6655,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;
@@ -6674,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,
@@ -6688,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) {
@@ -6729,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,
@@ -6745,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,
@@ -6753,7 +6951,8 @@ function ruleStylesNoRawTypography(ix) {
           allowed,
           suggestedValue: checked.suggestedValue,
           matchedToken: checked.matchedToken,
-          source: "css"
+          source: "css",
+          ...fixEmission?.downgradeReason ? { downgradeReason: fixEmission.downgradeReason } : {}
         }
       })
     );
@@ -6762,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;
@@ -6784,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,
@@ -6792,7 +6998,8 @@ function ruleStylesNoRawTypography(ix) {
           allowed,
           suggestedValue: checked.suggestedValue,
           matchedToken: checked.matchedToken,
-          source: "jsx"
+          source: "jsx",
+          ...fixEmission?.downgradeReason ? { downgradeReason: fixEmission.downgradeReason } : {}
         }
       })
     );
@@ -6822,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
     };
@@ -6844,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) {
@@ -7526,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;
@@ -7536,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,
@@ -7556,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"
           }
         })
@@ -7576,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";
@@ -7667,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";
 }
@@ -7674,7 +7912,11 @@ function isDenyEligible(finding, failOnWarnings) {
   if (!BLOCKING_RULE_ALLOWLIST.has(finding.ruleId)) return false;
   if (finding.attributes?.advisory === true) return false;
   if (!gatesCi(finding, failOnWarnings)) return false;
-  if (finding.fix?.deterministic === false) return false;
+  if (finding.fix?.deterministic === false) {
+    if (finding.ruleId !== "components/prefer-library" || finding.attributes?.propCompatibility !== "observed-complete") {
+      return false;
+    }
+  }
   return true;
 }
 
@@ -7682,7 +7924,7 @@ function isDenyEligible(finding, failOnWarnings) {
 var RULE_TIER = {
   // ---- Tier A — contract vocabulary -------------------------------------
   "components/prefer-library": "contract",
-  // canonical-component bypass (FUI1001/1004)
+  // canonical-component bypass (FUI1004)
   "tokens/css-vars-must-be-defined": "contract",
   // token drift (FUI2015)
   // ---- Tier B — generic hygiene -----------------------------------------
@@ -7947,6 +8189,7 @@ function evaluateGovernanceIntegrity(input) {
       componentsFamily.remediation = "add govern.canonicalSources (a directory source, or npm/registry with a non-empty include) or designSystem.path/packageName";
     } else {
       componentsFamily.reason = "components/prefer-library not enabled";
+      componentsFamily.remediation = "add govern.canonicalSources (a directory source, or npm/registry with a non-empty include) or designSystem.path/packageName";
     }
   }
   const cssVarsActive = input.cssVarsActive ?? policyDeclaresCssVars(input.policy);
@@ -8035,6 +8278,29 @@ function evaluateGovernanceIntegrity(input) {
 // src/contract/preimage.ts
 var CONTRACT_DOMAINS = ["components", "tokens", "canonicalMap", "policy"];
 var CONTRACT_PREIMAGE_SCHEMA = "fcid-preimage:v1";
+var CONTRACT_PREIMAGE_CAPABILITY_HEADER = "X-Fragments-Contract-Preimage";
+var SHA256_HEX_PATTERN = /^[0-9a-f]{64}$/u;
+function verifiedContractPreimageFromPin(pin) {
+  if (pin.preimageSchema !== CONTRACT_PREIMAGE_SCHEMA || !SHA256_HEX_PATTERN.test(pin.contractHash) || !pin.domainHashes || typeof pin.domainHashes !== "object") {
+    return null;
+  }
+  const keys = Object.keys(pin.domainHashes).sort();
+  const expectedKeys = [...CONTRACT_DOMAINS].sort();
+  if (keys.length !== expectedKeys.length || keys.some((key, index) => key !== expectedKeys[index])) {
+    return null;
+  }
+  const domains = Object.fromEntries(
+    CONTRACT_DOMAINS.map((domain) => [domain, pin.domainHashes?.[domain]])
+  );
+  if (CONTRACT_DOMAINS.some((domain) => !SHA256_HEX_PATTERN.test(domains[domain] ?? ""))) {
+    return null;
+  }
+  const preimage = {
+    schema: CONTRACT_PREIMAGE_SCHEMA,
+    domains
+  };
+  return contractHash(preimage) === pin.contractHash ? preimage : null;
+}
 function sortCanonical(items) {
   return items.map((item) => ({ item, key: canonicalPreimage(item) })).sort((a, b) => a.key < b.key ? -1 : a.key > b.key ? 1 : 0).map(({ item }) => item);
 }
@@ -8358,15 +8624,18 @@ function readPreferLibraryRule(config) {
 }
 export {
   AGENT_CONTEXT_RELATIVE_PATH,
+  AGENT_FORMAT_SCHEMA_VERSION,
   BLOCKING_RULE_ALLOWLIST,
   BRAND,
   CATALOG_FIXTURE_A_FCID,
   CODES,
   CONTRACT_DOMAINS,
+  CONTRACT_PREIMAGE_CAPABILITY_HEADER,
   CONTRACT_PREIMAGE_SCHEMA,
   DEFAULTS,
   DEFAULT_ENHANCED_STYLE_PROPERTIES,
   DEFAULT_STYLE_PROPERTIES,
+  EVIDENCE_ORDER,
   EXPLAIN_URL_BASE,
   FRAGMENTS_INTERNAL_RULE_IDS,
   FactIndex,
@@ -8388,7 +8657,10 @@ export {
   SEVERITIES,
   SEVERITY_RANK,
   SEVERITY_WEIGHTS,
+  agentErrorEnvelopeSchema,
   agentFormatSchema,
+  agentIntegritySchema,
+  agentOutputSchema,
   aiMetadataSchema,
   analyzeComposition,
   asComponentId,
@@ -8415,6 +8687,7 @@ export {
   byCode,
   byRuleId,
   calculateDeltaE,
+  canBlock,
   canonicalJson,
   canonicalPreimage,
   canonicalizeOwnedComponentId,
@@ -8705,6 +8978,7 @@ export {
   topologyBase,
   usePreviewVariantRuntime,
   validatorResultSchema,
+  verifiedContractPreimageFromPin,
   violationSchema,
   vocabularyRank
 };