@usefragments/core 1.0.0 → 1.2.0

package/src/contract/preimage.ts

@@ -139,6 +139,8 @@ export interface ContractCatalogInput {
 // ---------------------------------------------------------------------------
 
 export const CONTRACT_PREIMAGE_SCHEMA = "fcid-preimage:v1" as const;
+/** Request header used by clients that can verify and consume this preimage. */
+export const CONTRACT_PREIMAGE_CAPABILITY_HEADER = "X-Fragments-Contract-Preimage" as const;
 
 /**
  * The hashed identity record: four domain sub-hashes plus the projection schema
@@ -150,6 +152,60 @@ export interface ContractPreimage {
   domains: Record<ContractDomain, string>;
 }
 
+/**
+ * Wire-compatible identity pin carried by Cloud policy responses. Older
+ * contract rows may omit the schema/domains, so every field except the FCID is
+ * intentionally nullable at this boundary.
+ */
+export interface ContractIdentityPin {
+  contractHash: string;
+  preimageSchema?: string | null;
+  domainHashes?: Readonly<Record<string, string>> | null;
+}
+
+const SHA256_HEX_PATTERN = /^[0-9a-f]{64}$/u;
+
+/**
+ * Reconstruct and verify the canonical preimage behind a published FCID.
+ *
+ * This is the only supported bridge from the additive ledger/wire shape
+ * (`preimageSchema` + `domainHashes`) back to the hash input. Consumers must
+ * not trust `enforcedIdentityComparable` on its own: a malformed, partial, or
+ * internally inconsistent pin returns `null` and therefore fails closed.
+ */
+export function verifiedContractPreimageFromPin(pin: ContractIdentityPin): ContractPreimage | null {
+  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]])
+  ) as Record<ContractDomain, string | undefined>;
+  if (CONTRACT_DOMAINS.some((domain) => !SHA256_HEX_PATTERN.test(domains[domain] ?? ""))) {
+    return null;
+  }
+
+  const preimage: ContractPreimage = {
+    schema: CONTRACT_PREIMAGE_SCHEMA,
+    domains: domains as Record<ContractDomain, string>,
+  };
+  return contractHash(preimage) === pin.contractHash ? preimage : null;
+}
+
 /**
  * Sort projected elements by their canonical serialization: total, deterministic,
  * and independent of adapter iteration order, without per-type comparators.

package/src/facts/builders.ts

@@ -461,6 +461,7 @@ export function makeJsxComponentPreferredFact(input: {
 export function makeTokenDefinitionFact(input: {
   name: string;
   value: string;
+  location?: TokenDefinitionFact["location"];
   category?: TokenDefinitionFact["category"];
   referenceFormat?: TokenDefinitionFact["referenceFormat"];
 }): TokenDefinitionFact {
@@ -469,6 +470,7 @@ export function makeTokenDefinitionFact(input: {
     kind: "token_definition",
     name: input.name,
     value: input.value,
+    ...(input.location ? { location: input.location } : {}),
     category: input.category,
     referenceFormat: input.referenceFormat,
   };

package/src/facts/fact-index.ts

@@ -58,6 +58,10 @@ function logicalComponentId(componentId: ComponentId): ComponentId {
 }
 
 function logicalFactForComparison(fact: Fact): Record<string, unknown> {
+  if (fact.kind === "token_definition") {
+    const { location: _location, ...logicalFact } = fact;
+    return logicalFact;
+  }
   if (fact.kind === "jsx_import_path_preferred") {
     return {
       ...fact,

package/src/facts/facts.test.ts

@@ -9,6 +9,7 @@ import {
   compileComponentFacts,
   compileGlobalGovernanceFacts,
   g,
+  makeTokenDefinitionFact,
   makeUsageNodeFact,
 } from "../index.js";
 import type { ComponentId, FactId, PropValueForbiddenFact } from "../index.js";
@@ -443,6 +444,54 @@ describe("FactIndex — query layer", () => {
     warn.mockRestore();
   });
 
+  it("does not treat token-definition provenance as a logical conflict", () => {
+    const ix = new FactIndex();
+    const warn = vi.spyOn(console, "warn").mockImplementation(() => {});
+    const first = makeTokenDefinitionFact({
+      name: "--fui-color-accent",
+      value: "#2563eb",
+      location: { file: "tokens/base.css", line: 2, column: 1 },
+    });
+    const second = makeTokenDefinitionFact({
+      name: "--fui-color-accent",
+      value: "#2563eb",
+      location: { file: "tokens/theme.css", line: 4, column: 1 },
+    });
+
+    ix.add(first);
+    ix.add(second);
+
+    expect(warn).not.toHaveBeenCalled();
+    expect(ix.get(first.id)).toEqual(first);
+    warn.mockRestore();
+  });
+
+  it("includes token-definition provenance in logical conflict warnings", () => {
+    const ix = new FactIndex();
+    const warn = vi.spyOn(console, "warn").mockImplementation(() => {});
+    const first = makeTokenDefinitionFact({
+      name: "--fui-color-accent",
+      value: "#2563eb",
+      location: { file: "tokens/base.css", line: 2, column: 1 },
+    });
+    const second = makeTokenDefinitionFact({
+      name: "--fui-color-accent",
+      value: "#1d4ed8",
+      location: { file: "tokens/theme.css", line: 4, column: 1 },
+    });
+
+    ix.add(first);
+    ix.add(second);
+
+    expect(warn).toHaveBeenCalledWith(
+      expect.stringMatching(
+        /conflicting facts.*kind=token_definition location=tokens\/theme\.css:4:1/
+      )
+    );
+    expect(ix.get(first.id)).toEqual(first);
+    warn.mockRestore();
+  });
+
   it("treats old and current owned component spellings as the same indexed facts", () => {
     const legacyId = asComponentId("@fragments-sdk/ui#Button");
     const currentId = asComponentId("@usefragments/ui#Button");

package/src/facts/types.ts

@@ -200,6 +200,7 @@ export interface JsxComponentPreferredFact extends BaseFact {
  */
 export interface TokenDefinitionFact extends BaseFact {
   kind: "token_definition";
+  location?: FactLocation;
   /** Token identifier, e.g., "fui-color-accent" or "--fui-color-accent". */
   name: string;
   /** Resolved value, e.g., "#2563eb". */

package/src/governance-integrity.test.ts

@@ -177,8 +177,10 @@ describe("evaluateGovernanceIntegrity", () => {
     };
     const verdict = evaluate({ policy, policySource: "config", declared: true });
     const hygiene = verdict.families.find((f) => f.id === "hygiene");
+    const components = verdict.families.find((f) => f.id === "components");
     expect(hygiene?.armed).toBe(true);
     expect(hygiene?.rules).toContain("styles/no-raw-color");
+    expect(components?.remediation).toContain("govern.canonicalSources");
     expect(verdict.status).toBe("degraded");
     // degraded is enforceable, so not CI-fatal
     expect(verdict.fatalForCi).toBe(false);

package/src/governance-integrity.ts

@@ -25,7 +25,11 @@ import { BLOCKING_RULE_ALLOWLIST } from "./rules/emit-gate.js";
 export type GovernanceIntegrityStatus = "healthy" | "degraded" | "inert";
 
 export type GovernanceIntegrityFamilyId =
-  "policy" | "components" | "tokens" | "hygiene" | "blocking-deny";
+  | "policy"
+  | "components"
+  | "tokens"
+  | "hygiene"
+  | "blocking-deny";
 
 export interface GovernanceIntegrityFamily {
   id: GovernanceIntegrityFamilyId;
@@ -177,6 +181,8 @@ export function evaluateGovernanceIntegrity(
         "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";
     }
   }
 

package/src/index.ts

@@ -62,7 +62,11 @@ export type { Severity, SeverityLevel } from "./severity.js";
 
 // Canonical TypeStyle schemas
 export {
+  AGENT_FORMAT_SCHEMA_VERSION,
+  agentErrorEnvelopeSchema,
   agentFormatSchema,
+  agentIntegritySchema,
+  agentOutputSchema,
   factEvidenceSchema,
   factLocationSchema,
   findingFixSchema,
@@ -83,7 +87,9 @@ export {
   violationSchema,
 } from "./schemas/index.js";
 export type {
+  AgentErrorEnvelope,
   AgentFormat,
+  AgentOutput,
   Fix,
   Finding as CanonicalFinding,
   GovernanceVerdict as CanonicalGovernanceVerdict,
@@ -763,6 +769,7 @@ export {
   catalogFixtureAContractPayload,
   catalogFixtureATokensDtcg,
   CONTRACT_DOMAINS,
+  CONTRACT_PREIMAGE_CAPABILITY_HEADER,
   CONTRACT_PREIMAGE_SCHEMA,
   contractComponentsFromFragments,
   contractHash,
@@ -775,6 +782,7 @@ export {
   projectContractPreimage,
   serializeContractStamp,
   sha256Hex,
+  verifiedContractPreimageFromPin,
 } from "./contract/index.js";
 export {
   OWNED_PACKAGE_IDENTITY_EPOCH,
@@ -794,6 +802,7 @@ export type {
   ContractCatalogInput,
   ContractComponentInput,
   ContractDomain,
+  ContractIdentityPin,
   ContractPolicyInput,
   ContractPreimage,
   ContractPropMappingInput,

package/src/rules/components-prefer-library.ts

@@ -24,6 +24,8 @@ export const RULE_VERSION = "1";
 
 interface CanonicalMappingOption {
   name: string;
+  /** Internal conform-boundary assertion; only the conform policy builder sets it. */
+  conformStatus?: "confirmed";
   canonical?: string;
   htmlEquivalent?: string;
   /**
@@ -268,7 +270,8 @@ export function ruleComponentsPreferLibrary(ix: FactIndex): Finding[] {
     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") : undefined;
     const mapped = findMapping(node, nodeInputType, mappings);
@@ -281,6 +284,7 @@ export function ruleComponentsPreferLibrary(ix: FactIndex): Finding[] {
       const suggestedComponent = mapped.name;
       const suggestedImport = importPath ?? "the canonical library";
       const propMapping = mapped.propMapping ?? [];
+      const propCompatibility = assessMappedPropCompatibility(props, propMapping);
       const roleMatch = isRoleMatch(node, mapped);
       const precisionTier: RawHtmlPrecisionTier = roleMatch ? "role-reimpl" : "exact-html";
 
@@ -290,6 +294,12 @@ export function ruleComponentsPreferLibrary(ix: FactIndex): Finding[] {
         !ownedImportsEqual(imported.source, importPath) &&
         node.element === suggestedComponent
       ) {
+        // A same-name package import is not proof that the package implements
+        // our canonical primitive. For example, TanStack Router's `Link` and a
+        // design-system `Link` share a local JSX name but have different
+        // contracts. Only an unaliased local import is a useful guided
+        // candidate; package migrations need an explicit import policy.
+        if (!isLocalExactComponentImportRedirectCandidate(imported, suggestedComponent)) continue;
         const key = `${imported.file}\0${imported.local}\0${imported.source}\0${importPath}`;
         if (seenImportFixes.has(key)) continue;
         seenImportFixes.add(key);
@@ -297,8 +307,8 @@ export function ruleComponentsPreferLibrary(ix: FactIndex): Finding[] {
           makeFinding({
             ruleId: RULE_ID,
             ruleVersion: RULE_VERSION,
-            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: {
@@ -312,7 +322,7 @@ export function ruleComponentsPreferLibrary(ix: FactIndex): Finding[] {
               title: `Replace import path with "${importPath}"`,
               from: imported.source,
               to: importPath,
-              deterministic: true,
+              deterministic: false,
             },
             attributes: {
               rawValue: imported.source,
@@ -320,6 +330,8 @@ export function ruleComponentsPreferLibrary(ix: FactIndex): Finding[] {
               suggestedImport: importPath,
               canonical: mapped.canonical,
               confidence: mapped.confidence,
+              advisory: true,
+              contractProof: "missing",
             },
           })
         );
@@ -363,7 +375,11 @@ export function ruleComponentsPreferLibrary(ix: FactIndex): Finding[] {
                   title: `Replace <${node.element}> with <${suggestedComponent}>`,
                   from: node.element,
                   to: suggestedComponent,
-                  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,
                 },
               }
             : {}),
@@ -374,8 +390,14 @@ export function ruleComponentsPreferLibrary(ix: FactIndex): Finding[] {
             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,
             ...(roleMatch ? { matchedRole: node.role } : {}),
+            ...(isRawHtmlAdvisoryTier(precisionTier) ? { advisory: true } : {}),
           },
         })
       );
@@ -387,7 +409,8 @@ export function ruleComponentsPreferLibrary(ix: FactIndex): Finding[] {
     // canonical component name is very likely a hand-rolled reimplementation
     // (`<div className={styles.card}>` for a Card). class-name↔component is a
     // naming-intent signal, not structural proof — so this is advisory, capped at
-    // warn, carries no auto-fix, and never blocks a write (see emit-gate).
+    // warn, carries no auto-fix, and never blocks a write (see emit-gate). DOG-03
+    // backlog: deterministic canonical-shell signatures may promote proven matches.
     if (
       (node.element === "div" || node.element === "span") &&
       node.role === undefined &&
@@ -432,6 +455,57 @@ export function ruleComponentsPreferLibrary(ix: FactIndex): Finding[] {
     const suggestion = findSuggestionSource(suggestedComponent, sources);
     if (!suggestion) continue;
     if (!builtIn && !shouldSuggest(node, imported)) continue;
+
+    // An exact component-name match is either already canonical (handled near
+    // the top of the loop), a safely redirectable local component import, or an
+    // unrelated component that happens to share a name. Never report a
+    // replaceComponent X -> X no-op, and never infer that one package's `Link`
+    // is interchangeable with another package's `Link`.
+    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_ID,
+          ruleVersion: RULE_VERSION,
+          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;
+    }
     // Directory canonical sources are typically derived without an `include`
     // filter (cloud pushes `{ kind: "directory", path }` for every component
     // folder), so `sourceIncludesComponent` matches EVERY name. Without the same
@@ -495,7 +569,10 @@ export function ruleComponentsPreferLibrary(ix: FactIndex): Finding[] {
                 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,
               },
             }
           : {}),
@@ -505,6 +582,7 @@ export function ruleComponentsPreferLibrary(ix: FactIndex): Finding[] {
           suggestedImport,
           suggestedImportSourceKind: suggestion.kind,
           precisionTier,
+          propCompatibility: "unknown",
           ...(builtIn?.matchedRole ? { matchedRole: builtIn.matchedRole } : {}),
           ...(builtIn?.inputType ? { matchedInputType: builtIn.inputType } : {}),
           ...(isRawHtmlAdvisoryTier(precisionTier) ? { advisory: true } : {}),
@@ -689,6 +767,79 @@ function shouldSuggest(node: UsageNodeFact, imported: UsageImportFact | undefine
   return imported !== undefined;
 }
 
+interface PropCompatibilityAssessment {
+  complete: boolean;
+  unprovenProps: string[];
+}
+
+/**
+ * Prove that every observed prop can survive the component replacement.
+ *
+ * An explicit pass-through (`rawProp === canonicalProp`) is proof too. Spreads,
+ * missing entries, and value translations that cannot be applied exactly stay
+ * unresolved: the canonical mapping proves the target component, but it does
+ * not imply that the target forwards the native element's entire prop surface.
+ */
+function assessMappedPropCompatibility(
+  props: readonly UsagePropResolvedFact[],
+  mappings: ReadonlyArray<NonNullable<CanonicalMappingOption["propMapping"]>[number]>
+): PropCompatibilityAssessment {
+  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: NonNullable<CanonicalMappingOption["propMapping"]>[number],
+  prop: UsagePropResolvedFact
+): boolean {
+  const renames = mapping.rawProp !== mapping.canonicalProp;
+  const valueMap = mapping.valueMap;
+  const translatesValue = valueMap !== undefined && Object.keys(valueMap).length > 0;
+
+  // The conform editor can only rename simple JSX identifiers. A pass-through
+  // needs no edit and can therefore retain valid JSX names such as aria-label.
+  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: UsageImportFact,
+  componentName: string
+): boolean {
+  return isUnaliasedNamedImport(usage, componentName) && isProjectLocalImportSource(usage.source);
+}
+
+function isUnaliasedNamedImport(usage: UsageImportFact, componentName: string): boolean {
+  return isSimpleComponentBinding(usage, componentName) && usage.imported === componentName;
+}
+
+function isSimpleComponentBinding(usage: UsageImportFact, componentName: string): boolean {
+  return usage.namespace !== true && usage.local === componentName;
+}
+
+function isProjectLocalImportSource(source: string): boolean {
+  return (
+    source.startsWith(".") ||
+    source.startsWith("/") ||
+    source.startsWith("@/") ||
+    source.startsWith("~/")
+  );
+}
+
 /**
  * Case-INSENSITIVE equality for the `htmlEquivalent` ↔ raw-tag comparison.
  * Raw HTML tag names are case-insensitive, but a catalog/author can store a
@@ -734,6 +885,7 @@ function isCanonicalMappingOption(value: unknown): value is CanonicalMappingOpti
   if (record.htmlType !== undefined && typeof record.htmlType !== "string") return false;
   if (record.importPath !== undefined && typeof record.importPath !== "string") return false;
   if (record.confidence !== undefined && typeof record.confidence !== "number") return false;
+  if (record.conformStatus !== undefined && record.conformStatus !== "confirmed") return false;
   if (
     record.declaredHtmlEquivalent !== undefined &&
     typeof record.declaredHtmlEquivalent !== "boolean"
@@ -910,6 +1062,12 @@ function sourceLabel(source: CanonicalSource): string {
   return source.path;
 }
 
+function canonicalImportPath(source: CanonicalSource): string | undefined {
+  if (source.kind === "npm") return source.specifier;
+  if (source.kind === "registry") return source.importPath;
+  return undefined;
+}
+
 function isCanonicalSourceImplementationFile(
   file: string,
   sources: readonly CanonicalSource[]

package/src/rules/emit-gate.test.ts

@@ -35,8 +35,30 @@ describe("isDenyEligible", () => {
     expect(isDenyEligible(warn, true)).toBe(true);
   });
 
-  it("does not deny an explicitly non-deterministic (heuristic) fix", () => {
-    const heuristic = { ...base, fix: { deterministic: false } } as unknown as Finding;
+  it("does not deny an explicitly non-deterministic token heuristic", () => {
+    const heuristic = {
+      ...base,
+      ruleId: "styles/no-raw-color",
+      fix: { deterministic: false },
+    } as unknown as Finding;
     expect(isDenyEligible(heuristic, false)).toBe(false);
   });
+
+  it("denies an exact canonical-component violation while withholding its generic fix", () => {
+    const exactComponent = {
+      ...base,
+      fix: { deterministic: false },
+      attributes: { precisionTier: "exact-html", propCompatibility: "observed-complete" },
+    } as unknown as Finding;
+    expect(isDenyEligible(exactComponent, false)).toBe(true);
+  });
+
+  it("keeps a component replacement advisory when observed props are not proven compatible", () => {
+    const incompleteComponent = {
+      ...base,
+      fix: { deterministic: false },
+      attributes: { precisionTier: "exact-html", propCompatibility: "incomplete" },
+    } as unknown as Finding;
+    expect(isDenyEligible(incompleteComponent, false)).toBe(false);
+  });
 });

package/src/rules/emit-gate.ts

@@ -39,7 +39,7 @@ export function gatesCi(finding: Finding, failOnWarnings: boolean): boolean {
   return level === "error" || (failOnWarnings && level === "warn");
 }
 
-/** A finding may deny iff it is allowlisted, gates CI, and is not a flagged-heuristic fix. */
+/** A finding may deny iff it is allowlisted, gates CI, and is not heuristic. */
 export function isDenyEligible(finding: Finding, failOnWarnings: boolean): boolean {
   if (!BLOCKING_RULE_ALLOWLIST.has(finding.ruleId)) return false;
   // Advisory findings — the low-confidence precision tiers a rule flags with
@@ -50,11 +50,19 @@ export function isDenyEligible(finding: Finding, failOnWarnings: boolean): boole
   // confident" principle as the non-deterministic-fix guard below.
   if (finding.attributes?.advisory === true) return false;
   if (!gatesCi(finding, failOnWarnings)) return false;
-  // An explicitly non-deterministic fix is the engine's own "low confidence /
-  // ambiguous" signal (e.g. several tokens share a value, or a heuristic swap).
-  // Those stay advisory — only deny when the engine is confident. A finding with
-  // no fix at all (e.g. a raw color with no matching token) still gates CI, so it
-  // remains deny-eligible.
-  if (finding.fix?.deterministic === false) return false;
+  // Most explicitly non-deterministic fixes are the engine's own low-confidence
+  // signal (for example, several tokens share a value). A prefer-library
+  // finding may still be an exact policy violation, but hard-denying it is only
+  // DX-safe when the configured mapping proves that every observed prop can be
+  // preserved. The conform AST preflight independently checks the source and
+  // binding before any edit is applied.
+  if (finding.fix?.deterministic === false) {
+    if (
+      finding.ruleId !== "components/prefer-library" ||
+      finding.attributes?.propCompatibility !== "observed-complete"
+    ) {
+      return false;
+    }
+  }
   return true;
 }

package/src/rules/fix-availability.ts

@@ -0,0 +1,33 @@
+/**
+ * Whether each implemented rule can emit a fix on at least one finding.
+ *
+ * Rule-backed FUI registry entries derive their `fixAvailable` value from this
+ * map. A parity test keeps the keys in lock-step with `RULES`, so capability is
+ * declared once instead of being repeated in rule and code registries.
+ */
+export const RULE_FIX_AVAILABLE = {
+  "components/unknown-prop": false,
+  "components/forbidden-prop-value": true,
+  "props/invalid-value": true,
+  "imports/preferred-path": true,
+  "components/preferred-component": true,
+  "components/prefer-library": true,
+  "styles/no-raw-color": true,
+  "styles/no-raw-dimensions": true,
+  "styles/no-raw-spacing": true,
+  "styles/no-raw-typography": true,
+  "tailwind/arbitrary-color": false,
+  "tailwind/arbitrary-spacing": true,
+  "tailwind/forbidden-palette": true,
+  "tailwind/off-scale-spacing-token": true,
+  "tailwind/raw-color-via-token": false,
+  "tailwind/unknown-class": false,
+  "tokens/require-dual-fallback": true,
+  "tokens/css-vars-must-be-defined": false,
+  "theme/no-theme-coupled-literal": false,
+  "a11y/required-accessible-name": false,
+  "composition/cardinality": false,
+  "composition/co-occurrence": false,
+} as const satisfies Readonly<Record<string, boolean>>;
+
+export type RuleWithFixAvailability = keyof typeof RULE_FIX_AVAILABLE;