@usefragments/core 1.5.0 → 1.5.2

package/dist/index.js

@@ -49,6 +49,7 @@ import {
   bridgeSourceViolations,
   byCode,
   byRuleId,
+  canonicalBridgeV1Schema,
   canonicalJson,
   compileComponentFacts,
   compileGlobalGovernanceFacts,
@@ -111,7 +112,7 @@ import {
   ownedImportsEqual,
   resolveComponentGovernance,
   scaleGovernanceRecordSchema
-} from "./chunk-HXGE3O2F.js";
+} from "./chunk-BAHCOAVG.js";
 import {
   AGENT_FORMAT_SCHEMA_VERSION,
   agentErrorEnvelopeSchema,
@@ -136,7 +137,7 @@ import {
   suppressionDirectiveSchema,
   validatorResultSchema,
   violationSchema
-} from "./chunk-57QDBEHQ.js";
+} from "./chunk-ZHS52OT4.js";
 import {
   OWNED_PACKAGE_IDENTITY_EPOCH,
   OWNED_PACKAGE_IDENTITY_SOURCE_SHA256,
@@ -1687,6 +1688,14 @@ var tokenConfigSchema = z4.object({
   // vocabulary seeds the known-token set (#7c). A packages-only tokens block
   // is valid — see the superRefine below.
   packages: z4.array(z4.string().min(1)).optional(),
+  aliases: z4.record(z4.string().min(1)).optional(),
+  upstream: z4.array(
+    z4.object({
+      packageName: z4.string().min(1),
+      version: z4.string().min(1).optional(),
+      digest: z4.string().regex(/^[a-f0-9]{64}$/u).optional()
+    })
+  ).optional(),
   exclude: z4.array(repoRelativePathSchema).optional(),
   themeSelectors: z4.record(z4.string()).optional(),
   enabled: z4.boolean().optional(),
@@ -1832,9 +1841,14 @@ var governedFragmentDefinitionSchema = z4.object({
 var recipeDefinitionSchema = blockDefinitionSchema;
 
 // src/config.ts
+var RAW_CONFIG_DECLARATION = /* @__PURE__ */ Symbol.for("@usefragments/core/raw-config-declaration");
 function formatZodErrors(errors) {
   return errors.map((error) => `  - ${error.path.join(".")}: ${error.message}`).join("\n");
 }
+function configDeclarationForDiagnostics(config) {
+  if (!config || typeof config !== "object") return config;
+  return config[RAW_CONFIG_DECLARATION] ?? config;
+}
 function defineConfig(config) {
   const normalized = normalizeGovernanceConfig(config);
   const result = fragmentsConfigSchema.safeParse(normalized);
@@ -1842,6 +1856,12 @@ function defineConfig(config) {
     throw new Error(`Invalid fragments config:
 ${formatZodErrors(result.error.errors)}`);
   }
+  Object.defineProperty(result.data, RAW_CONFIG_DECLARATION, {
+    value: normalized,
+    enumerable: false,
+    configurable: false,
+    writable: false
+  });
   return result.data;
 }
 
@@ -4775,13 +4795,20 @@ function isExemptColor(value, except) {
   }
   return false;
 }
-function tokenReference(name) {
-  if (name.startsWith("$")) return name;
-  const cssVarName = name.startsWith("--") ? name : `--${name.replace(/\./g, "-")}`;
-  return `var(${cssVarName})`;
+function tokenReference(token) {
+  if (token.referenceFormat === "css-var") {
+    const cssVarName = [token.name, ...token.sourceNames ?? []].find(
+      (name) => name.startsWith("--")
+    );
+    return cssVarName ? `var(${cssVarName})` : token.name;
+  }
+  if (token.referenceFormat === "scss-var") {
+    return [token.name, ...token.sourceNames ?? []].find((name) => name.startsWith("$")) ?? (token.name.startsWith("--") ? `$${token.name.slice(2)}` : token.name);
+  }
+  return token.sourceNames?.[0] ?? token.name;
 }
 function isApplicableTokenReference(referenceFormat) {
-  return referenceFormat === void 0 || referenceFormat === "css-var" || referenceFormat === "scss-var";
+  return referenceFormat === "css-var" || referenceFormat === "scss-var";
 }
 
 // src/rules/a11y-required-accessible-name.ts
@@ -4938,6 +4965,77 @@ function isEnforceableHtmlEquivalent(args) {
   return builtIn !== null && builtIn.canonical === args.canonical;
 }
 
+// src/canonical-direction.ts
+function projectCanonicalDirectionConflicts(ix, canonicalSources) {
+  const npmSources = canonicalSources.filter(
+    (source) => source.kind === "npm"
+  );
+  if (npmSources.length === 0) return [];
+  const identityByComponent = new Map(
+    ix.byKind("component_identity").map((identity) => [identity.componentKey, identity])
+  );
+  const conflicts = [];
+  for (const definition of ix.byKind("component_definition")) {
+    if (!definition.exported || definition.renderRoot.resolution !== "canonical") continue;
+    const target = npmTarget(definition.renderRoot.canonical, npmSources);
+    if (!target) continue;
+    const identity = identityByComponent.get(definition.componentKey);
+    if (identity?.decisionId && decisionTargetsExport(identity.canonicalTarget, target.exportName)) {
+      if (identity.state === "shadow") continue;
+      if (identity.state === "variant" && identity.confidence === "confirmed") {
+        conflicts.push({
+          ...target,
+          wrapperComponentKey: definition.componentKey,
+          wrapperFile: definition.file,
+          wrapperExportName: definition.exportName,
+          state: "sanctioned"
+        });
+        continue;
+      }
+    }
+    conflicts.push({
+      ...target,
+      wrapperComponentKey: definition.componentKey,
+      wrapperFile: definition.file,
+      wrapperExportName: definition.exportName,
+      state: "unresolved"
+    });
+  }
+  return conflicts.sort(
+    (left, right) => left.packageName.localeCompare(right.packageName) || left.exportName.localeCompare(right.exportName) || left.wrapperComponentKey.localeCompare(right.wrapperComponentKey)
+  );
+}
+function canonicalDirectionConflictsTarget(conflicts, importPath, exportName) {
+  if (!importPath) return false;
+  return conflicts.some(
+    (conflict) => ownedImportMatchesRoot(importPath, conflict.packageName) && conflict.exportName === exportName
+  );
+}
+function npmTarget(canonicalTarget, sources) {
+  const separator = canonicalTarget.lastIndexOf("#");
+  if (separator <= 0 || separator === canonicalTarget.length - 1) return null;
+  const importPath = canonicalTarget.slice(0, separator);
+  const imported = canonicalTarget.slice(separator + 1).split(".").at(-1);
+  if (!imported) return null;
+  for (const source of sources) {
+    if (!ownedImportMatchesRoot(importPath, source.specifier)) continue;
+    const subpath = packageSubpath(importPath, source.specifier);
+    const exportName = imported === "default" ? subpath.split("/").filter(Boolean).at(-1) : imported;
+    if (!exportName) continue;
+    if (source.exclude?.includes(exportName)) continue;
+    if (source.include && !source.include.includes(exportName)) continue;
+    return { packageName: source.specifier, exportName };
+  }
+  return null;
+}
+function packageSubpath(importPath, packageName) {
+  return importPath === packageName ? "" : importPath.slice(packageName.length + 1);
+}
+function decisionTargetsExport(target, exportName) {
+  if (!target) return true;
+  return target === exportName || target.split("#").at(-1)?.split(".").at(-1) === exportName;
+}
+
 // src/rules/components-prefer-library.ts
 var RULE_ID2 = "components/prefer-library";
 var RULE_VERSION2 = "1";
@@ -5081,8 +5179,12 @@ function findClassNameReimpl(node, classTokensByNode, targets) {
 function ruleComponentsPreferLibrary(ix) {
   const policy = ix.policy.ruleConfig(RULE_ID2);
   if (!policy?.enabled) return [];
-  const sources = canonicalSourcesFromPolicy(policy.options?.canonicalSources);
-  const mappings = canonicalMappingsFromPolicy(policy.options?.canonicalMappings);
+  const configuredSources = canonicalSourcesFromPolicy(policy.options?.canonicalSources);
+  const conflicts = projectCanonicalDirectionConflicts(ix, configuredSources);
+  const sources = configuredSources.map((source) => suppressConflictedExports(source, conflicts));
+  const mappings = canonicalMappingsFromPolicy(policy.options?.canonicalMappings).filter(
+    (mapping) => !canonicalDirectionConflictsTarget(conflicts, mapping.importPath, mapping.name)
+  );
   if (sources.length === 0 && mappings.length === 0) return [];
   const importsByFileAndLocal = indexImportsByFileAndLocal(ix);
   const propsByNode = indexPropsByNodeId(ix);
@@ -5345,6 +5447,16 @@ function ruleComponentsPreferLibrary(ix) {
   }
   return findings;
 }
+function suppressConflictedExports(source, conflicts) {
+  if (source.kind !== "npm") return source;
+  const names = conflicts.filter((conflict) => ownedImportMatchesRoot(source.specifier, conflict.packageName)).map((conflict) => conflict.exportName);
+  if (names.length === 0) return source;
+  const blocked = new Set(names);
+  if (source.include) {
+    return { ...source, include: source.include.filter((name) => !blocked.has(name)) };
+  }
+  return { ...source, exclude: [.../* @__PURE__ */ new Set([...source.exclude ?? [], ...names])].sort() };
+}
 function indexShadowRenderRootNodeIds(ix) {
   const identities = ix.byKind("component_identity");
   if (identities.length === 0) return /* @__PURE__ */ new Set();
@@ -6117,6 +6229,18 @@ function ruleJsxPreferredImportPath(ix) {
   const seen = /* @__PURE__ */ new Set();
   for (const usage of ix.byKind("usage_import")) {
     const matches = policies.filter((policy) => {
+      if (policy.bridge) {
+        if (policy.bridge.implementationFiles.some((file) => sameRepoPath(file, usage.file))) {
+          return false;
+        }
+        if (!ownedImportMatchesRoot(usage.source, policy.from)) return false;
+        if (ownedImportsEqual(usage.source, policy.from)) {
+          return usage.imported === policy.bridge.underlyingExportName;
+        }
+        const subpath = usage.source.slice(policy.from.length + 1);
+        const leaf = subpath.split("/").at(-1);
+        return leaf === policy.bridge.underlyingExportName && (usage.imported === "default" || usage.imported === policy.bridge.underlyingExportName);
+      }
       if (!ownedImportsEqual(policy.from, usage.source)) return false;
       if (policy.imported !== void 0 && policy.imported !== usage.imported) return false;
       return true;
@@ -6132,7 +6256,7 @@ function ruleJsxPreferredImportPath(ix) {
           ruleId: RULE_ID7,
           ruleVersion: RULE_VERSION8,
           severity: policy.severity,
-          message: `Import from "${usage.source}" should use "${policy.to}".`,
+          message: policy.bridge ? `Import ${policy.bridge.underlyingExportName} through the confirmed local ${policy.bridge.localExportName} wrapper from "${policy.to}".` : `Import from "${usage.source}" should use "${policy.to}".`,
           location: usage.location,
           evidence: ix.evidence([usage.id, policy.id]),
           fingerprintIdentity: {
@@ -6143,7 +6267,7 @@ function ruleJsxPreferredImportPath(ix) {
             line: usage.location.line,
             column: usage.location.column
           },
-          fix: {
+          fix: policy.bridge ? void 0 : {
             kind: "replaceImport",
             title: policy.because ?? `Replace import path with "${policy.to}"`,
             from: usage.source,
@@ -6155,7 +6279,14 @@ function ruleJsxPreferredImportPath(ix) {
             suggestedImport: policy.to,
             imported: usage.imported,
             local: usage.local,
-            rawValue: usage.source
+            rawValue: usage.source,
+            ...policy.bridge ? {
+              canonicalBridge: true,
+              canonicalTarget: policy.bridge.componentKey,
+              suggestedComponent: policy.bridge.localExportName,
+              implementationFiles: policy.bridge.implementationFiles,
+              decisionSource: policy.bridge.decisionSource
+            } : {}
           }
         })
       );
@@ -6163,6 +6294,12 @@ function ruleJsxPreferredImportPath(ix) {
   }
   return findings;
 }
+function sameRepoPath(left, right) {
+  return normalizeRepoPath(left) === normalizeRepoPath(right);
+}
+function normalizeRepoPath(path) {
+  return path.replace(/\\/gu, "/").replace(/^\.\//u, "");
+}
 
 // src/rules/props-invalid-value.ts
 var RULE_ID8 = "props/invalid-value";
@@ -6373,13 +6510,36 @@ function srgbGamma(linear) {
   return clamped <= 31308e-7 ? 12.92 * clamped : 1.055 * Math.pow(clamped, 1 / 2.4) - 0.055;
 }
 
+// src/rules/token-candidates.ts
+function normalizedTokenValue(token) {
+  const value = token.value.trim();
+  return token.category === "color" ? normalizeColor(value) : value.replace(/\s+/g, " ");
+}
+function localTokenCandidates(ix, category) {
+  const all = ix.tokens.list();
+  const upstreamByName = /* @__PURE__ */ new Map();
+  for (const token of all) {
+    if (token.role !== "upstream") continue;
+    const matches = upstreamByName.get(token.name) ?? [];
+    matches.push(token);
+    upstreamByName.set(token.name, matches);
+  }
+  return all.filter((token) => {
+    if (token.role === "upstream" || category !== void 0 && token.category !== category) {
+      return false;
+    }
+    const matches = upstreamByName.get(token.upstreamName ?? token.name) ?? [];
+    return matches.length !== 1 || normalizedTokenValue(token) === normalizedTokenValue(matches[0]);
+  });
+}
+
 // src/rules/styles-no-raw-color.ts
 var RULE_ID9 = "styles/no-raw-color";
 var RULE_VERSION10 = "1";
 function ruleStylesNoRawColor(ix) {
   const policy = ix.policy.rawColorPolicy();
   if (!policy) return [];
-  const colorTokens = ix.tokens.byCategory("color");
+  const colorTokens = localTokenCandidates(ix, "color");
   const preferLabel = policy.prefer === "token" ? "design token" : "CSS variable";
   const findings = [];
   const advisorySeverity = policy.severity === "error" ? "warn" : policy.severity;
@@ -6633,7 +6793,7 @@ function normalizeColor2(value) {
   return lower;
 }
 function buildTokenFix(property, rawValue, rawColor, match, ix) {
-  const reference = tokenReference(match.token.name);
+  const reference = tokenReference(match.token);
   const value = replaceRawColor(rawValue, rawColor, reference);
   return emitFix(
     {
@@ -6668,8 +6828,8 @@ function ruleStylesNoRawDimensions(ix) {
   const policy = ix.policy.rawDimensionPolicy();
   if (!policy) return [];
   const appliesTo = new Set(policy.appliesTo);
-  const spacingTokens = ix.tokens.byCategory("spacing");
-  const radiusTokens = ix.tokens.byCategory("radius");
+  const spacingTokens = localTokenCandidates(ix, "spacing");
+  const radiusTokens = localTokenCandidates(ix, "radius");
   const preferLabel = policy.prefer === "token" ? "design token" : "CSS variable";
   const findings = [];
   for (const decl of ix.byKind("style_declaration")) {
@@ -6880,9 +7040,7 @@ function normalizeDimension(value) {
   return `${parsed.value}${parsed.unit ?? "px"}`;
 }
 function tokenVar(token) {
-  if (token.name.startsWith("$")) return token.name;
-  const cssVarName = token.name.startsWith("--") ? token.name : `--${token.name.replace(/\./g, "-")}`;
-  return `var(${cssVarName})`;
+  return tokenReference(token);
 }
 
 // src/rules/spacing-resolution.ts
@@ -6920,7 +7078,7 @@ function resolveSpacingValue(input) {
         continue;
       }
       anyViolation = true;
-      const reference = tokenReference(exactToken.name);
+      const reference = tokenReference(exactToken);
       if (!normalized.deterministicFix) allValuePreserving = false;
       suggestedParts.push(reference);
       if (!firstViolation) {
@@ -6952,7 +7110,7 @@ function resolveSpacingValue(input) {
     } else {
       const nearestToken = input.tokens.get(Math.abs(nearest));
       suggestedToken = nearestToken?.name;
-      suggestedPart = nearestToken ? tokenReference(nearestToken.name) : input.bareNumberFix ? `${nearest}` : `${nearest}${input.scale.unit}`;
+      suggestedPart = nearestToken ? tokenReference(nearestToken) : input.bareNumberFix ? `${nearest}` : `${nearest}${input.scale.unit}`;
       suggestedParts.push(suggestedPart);
       if (!normalized.deterministicFix) reliableSuggestion = false;
     }
@@ -7004,7 +7162,7 @@ function ruleStylesNoRawSpacing(ix) {
   const lookupFor = (scale) => {
     let lookup = lookupCache.get(scale.name);
     if (!lookup) {
-      lookup = buildSpacingTokenLookup(ix.tokens.byCategory("spacing"), scale);
+      lookup = buildSpacingTokenLookup(localTokenCandidates(ix, "spacing"), scale);
       lookupCache.set(scale.name, lookup);
     }
     return lookup;
@@ -7042,7 +7200,7 @@ function checkDeclaration(ix, decl, lookupFor) {
     ruleId: RULE_ID11,
     ruleVersion: RULE_VERSION12,
     severity: policy.severity,
-    message: spacingMessage(decl.property, decl.value, allowed, scale.unit, checked),
+    message: spacingMessage(decl.property, decl.value, allowed, scale, checked),
     location: decl.location,
     evidence: ix.evidence([decl.id, policy.id, scale.id]),
     fingerprintIdentity: {
@@ -7097,7 +7255,7 @@ function checkInlineStyle(ix, inline, componentByNode, lookupFor) {
     ruleId: RULE_ID11,
     ruleVersion: RULE_VERSION12,
     severity: policy.severity,
-    message: spacingMessage(inline.property, inline.value, allowed, scale.unit, checked),
+    message: spacingMessage(inline.property, inline.value, allowed, scale, checked),
     location: node.location,
     evidence: ix.evidence(evidenceIds),
     fingerprintIdentity: {
@@ -7138,21 +7296,21 @@ function buildSpacingFix(property, checked, ix) {
       deterministic: true
     },
     {
-      symbols: tokenSymbolsInText(checked.suggestedValue),
+      symbols: checked.matchedToken ? [checked.matchedToken] : tokenSymbolsInText(checked.suggestedValue),
       editKind: "replaceStyleValue",
       valuePreserving: checked.deterministicFix
     },
     ix
   );
 }
-function spacingMessage(property, value, allowed, unit, checked) {
+function spacingMessage(property, value, allowed, scale, checked) {
   if (checked.reason === "token-equivalent" && checked.matchedToken) {
     return `\`${property}: ${value}\` is a raw literal that matches token \`${checked.matchedToken}\`. Reference the token instead.`;
   }
   const sample = allowed.slice().sort((a, b) => a - b).slice(0, 6);
-  const suffix = `${sample.join(unit + ", ")}${unit}`;
+  const suffix = `${sample.join(scale.unit + ", ")}${scale.unit}`;
   const ellipsis = allowed.length > sample.length ? ", \u2026" : "";
-  return `\`${property}: ${value}\` is not on the spacing scale. Allowed: ${suffix}${ellipsis}.`;
+  return `\`${property}: ${value}\` is not on the \`${scale.name}\` scale. Allowed: ${suffix}${ellipsis}. Configure \`govern.scales.${scale.name}\` to change it.`;
 }
 
 // src/rules/styles-no-raw-typography.ts
@@ -7254,7 +7412,7 @@ function ruleStylesNoRawTypography(ix) {
 }
 function buildTypographyTokenLookup(ix, scale) {
   const out = /* @__PURE__ */ new Map();
-  for (const token of ix.tokens.byCategory("typography")) {
+  for (const token of localTokenCandidates(ix, "typography")) {
     const parsed = parseLengthValue(token.value);
     if (!parsed || parsed.unit === null) continue;
     const normalized = normalizeLengthForScale(parsed, scale);
@@ -7276,7 +7434,7 @@ function checkFontSize(raw, allowed, scale, tokens, bareNumberFix = false) {
   if (matchesScale(normalized.value, allowed)) {
     if (!exactToken) return null;
     return {
-      suggestedValue: tokenReference(exactToken.name),
+      suggestedValue: tokenReference(exactToken),
       fixEmittable: true,
       deterministicFix: normalized.deterministicFix,
       reason: "token-equivalent",
@@ -7288,7 +7446,7 @@ function checkFontSize(raw, allowed, scale, tokens, bareNumberFix = false) {
     return { fixEmittable: false, deterministicFix: false, reason: "off-scale" };
   }
   const nearestToken = tokens.get(Math.abs(nearest));
-  const suggestedValue = nearestToken ? tokenReference(nearestToken.name) : bareNumberFix ? `${nearest}` : `${nearest}${scale.unit}`;
+  const suggestedValue = nearestToken ? tokenReference(nearestToken) : bareNumberFix ? `${nearest}` : `${nearest}${scale.unit}`;
   return {
     suggestedValue,
     fixEmittable: normalized.deterministicFix,
@@ -7307,7 +7465,7 @@ function buildFix(property, checked, ix) {
       deterministic: true
     },
     {
-      symbols: tokenSymbolsInText(checked.suggestedValue),
+      symbols: checked.matchedToken ? [checked.matchedToken] : tokenSymbolsInText(checked.suggestedValue),
       editKind: "replaceStyleValue",
       valuePreserving: checked.deterministicFix
     },
@@ -7986,7 +8144,7 @@ var SASS_FILE = /\.(scss|sass)$/i;
 function ruleTokensRequireDualFallback(ix) {
   const policy = ix.policy.ruleConfig(RULE_ID20);
   if (!policy?.enabled) return [];
-  const tokensByCssVariable = indexTokensByCssVariable(ix.tokens.list());
+  const tokensByCssVariable = indexTokensByCssVariable(localTokenCandidates(ix));
   const findings = [];
   for (const decl of ix.byKind("style_declaration")) {
     if (!SASS_FILE.test(decl.file)) continue;
@@ -8135,6 +8293,57 @@ function skipToCloseParen(value, openParenIndex) {
   return value.length;
 }
 
+// src/rules/tokens-upstream-drift.ts
+var RULE_ID22 = "tokens/upstream-drift";
+var RULE_VERSION23 = "1";
+function ruleTokensUpstreamDrift(ix) {
+  const local = ix.tokens.list().filter((token) => token.role !== "upstream");
+  const upstream = ix.tokens.list().filter((token) => token.role === "upstream");
+  const upstreamByName = /* @__PURE__ */ new Map();
+  for (const token of upstream) {
+    const matches = upstreamByName.get(token.name) ?? [];
+    matches.push(token);
+    upstreamByName.set(token.name, matches);
+  }
+  const findings = [];
+  for (const token of local) {
+    const upstreamName = token.upstreamName ?? token.name;
+    const matches = (upstreamByName.get(upstreamName) ?? []).sort(
+      (a, b) => (a.sourceIdentity ?? "").localeCompare(b.sourceIdentity ?? "")
+    );
+    if (matches.length !== 1) continue;
+    const expected = matches[0];
+    if (normalizedTokenValue(token) === normalizedTokenValue(expected)) continue;
+    const location = token.location ?? {
+      file: token.sourceIdentity ?? "tokens",
+      line: 1,
+      column: 1
+    };
+    findings.push(
+      makeFinding({
+        ruleId: RULE_ID22,
+        ruleVersion: RULE_VERSION23,
+        severity: "warn",
+        message: `Local token ${token.name} is ${token.value}, but upstream ${upstreamName} is ${expected.value}.`,
+        location,
+        evidence: ix.evidence([token.id, expected.id]),
+        fingerprintIdentity: {
+          local: token.name,
+          upstream: upstreamName,
+          localSource: token.sourceIdentity,
+          upstreamSource: expected.sourceIdentity
+        },
+        attributes: {
+          local: { name: token.name, value: token.value, location: token.location },
+          upstream: { name: expected.name, value: expected.value, location: expected.location },
+          autoFix: false
+        }
+      })
+    );
+  }
+  return findings;
+}
+
 // src/rules/emit-gate.ts
 var BLOCKING_RULE_ALLOWLIST = /* @__PURE__ */ new Set([
   "styles/no-raw-color",
@@ -8175,6 +8384,8 @@ var RULE_TIER = {
   // canonical-component bypass (FUI1004)
   "tokens/css-vars-must-be-defined": "contract",
   // token drift (FUI2015)
+  "tokens/upstream-drift": "contract",
+  // authored local/upstream value drift (FUI2017)
   // ---- Tier B — generic hygiene -----------------------------------------
   "components/unknown-prop": "hygiene",
   "components/forbidden-prop-value": "hygiene",
@@ -8218,7 +8429,8 @@ function hygieneTierRuleIds() {
 var VOCABULARY_ORDER = [
   "components/shadow-component",
   "components/prefer-library",
-  "tokens/css-vars-must-be-defined"
+  "tokens/css-vars-must-be-defined",
+  "tokens/upstream-drift"
 ];
 function vocabularyRank(ruleId) {
   const index = VOCABULARY_ORDER.indexOf(ruleId);
@@ -8342,6 +8554,11 @@ var RULES = [
     version: "1",
     run: ruleTokensCssVarsMustBeDefined
   },
+  {
+    id: "tokens/upstream-drift",
+    version: "1",
+    run: ruleTokensUpstreamDrift
+  },
   {
     id: "theme/no-theme-coupled-literal",
     version: "1",
@@ -8406,6 +8623,207 @@ function policyDeclaresCssVars(policy) {
 function dedupe(values) {
   return [...new Set(values)];
 }
+var RULE_FAMILY_IDS = /* @__PURE__ */ new Set(["tokens/hardcoded-values", "components/usage", "a11y/wcag"]);
+var CONSUMED_RULE_IDS = new Set(Object.keys(RULE_TIER));
+var RECOGNIZED_RULE_IDS = /* @__PURE__ */ new Set([...CONSUMED_RULE_IDS, ...RULE_FAMILY_IDS]);
+var RULE_CONFIG_KEYS = /* @__PURE__ */ new Set(["enabled", "severity", "options"]);
+var PASSTHROUGH_KEYS = [
+  {
+    path: ["tokens"],
+    keys: [
+      "include",
+      "sources",
+      "packages",
+      "aliases",
+      "upstream",
+      "exclude",
+      "themeSelectors",
+      "enabled",
+      "format",
+      "namespace"
+    ]
+  },
+  {
+    path: ["screenshots"],
+    keys: ["viewport", "threshold", "delay", "outputDir", "themes"]
+  },
+  {
+    path: ["service"],
+    keys: ["poolSize", "idleTimeout"]
+  },
+  {
+    path: ["registry"],
+    keys: ["requireStory", "publicOnly", "categoryDepth", "includeProps", "embedFragments"]
+  },
+  {
+    path: ["govern", "tailwind"],
+    keys: ["palette"]
+  },
+  {
+    path: ["govern", "agent"],
+    keys: ["repairOrder"]
+  },
+  {
+    path: ["govern", "ci"],
+    keys: ["failOnWarnings"]
+  }
+];
+function objectRecord(value) {
+  if (!value || typeof value !== "object" || Array.isArray(value)) return void 0;
+  return value;
+}
+function valueAtPath(value, path) {
+  let current = value;
+  for (const segment of path) {
+    const record = objectRecord(current);
+    if (!record) return void 0;
+    current = record[segment];
+  }
+  return current;
+}
+function configPath(path) {
+  return path.reduce(
+    (output, segment) => typeof segment === "number" ? `${output}[${segment}]` : output ? `${output}.${segment}` : segment,
+    ""
+  );
+}
+function unconsumedKeyDiagnostic(path) {
+  const renderedPath = configPath(path);
+  return {
+    code: "FUI9004",
+    kind: "unconsumed-key",
+    severity: "warn",
+    path: renderedPath,
+    message: `${renderedPath} is not consumed by Fragments and has no effect. Remove it or use a supported config key.`
+  };
+}
+function collectStrippedKeys(authored, parsed, path, diagnostics) {
+  if (Array.isArray(authored)) {
+    if (!Array.isArray(parsed)) return;
+    authored.forEach((item, index) => {
+      collectStrippedKeys(item, parsed[index], [...path, index], diagnostics);
+    });
+    return;
+  }
+  const authoredRecord = objectRecord(authored);
+  const parsedRecord = objectRecord(parsed);
+  if (!authoredRecord || !parsedRecord) return;
+  for (const key of Object.keys(authoredRecord).sort()) {
+    if (!Object.prototype.hasOwnProperty.call(parsedRecord, key)) {
+      diagnostics.push(unconsumedKeyDiagnostic([...path, key]));
+      continue;
+    }
+    collectStrippedKeys(authoredRecord[key], parsedRecord[key], [...path, key], diagnostics);
+  }
+}
+function collectPassthroughKeys(authored, path, allowed, diagnostics) {
+  const record = objectRecord(valueAtPath(authored, path));
+  if (!record) return;
+  for (const key of Object.keys(record).sort()) {
+    if (!allowed.has(key)) diagnostics.push(unconsumedKeyDiagnostic([...path, key]));
+  }
+}
+function collectRuleConfigKeys(authored, path, diagnostics) {
+  const rules = objectRecord(valueAtPath(authored, path));
+  if (!rules) return;
+  for (const ruleId of Object.keys(rules).sort()) {
+    if (!RECOGNIZED_RULE_IDS.has(ruleId)) {
+      diagnostics.push(unconsumedKeyDiagnostic([...path, ruleId]));
+      continue;
+    }
+    const config = objectRecord(rules[ruleId]);
+    if (!config) continue;
+    for (const key of Object.keys(config).sort()) {
+      if (!RULE_CONFIG_KEYS.has(key)) {
+        diagnostics.push(unconsumedKeyDiagnostic([...path, ruleId, key]));
+      }
+    }
+  }
+}
+function collectPassthroughRecordValues(authored, path, allowed, diagnostics) {
+  const entries = objectRecord(valueAtPath(authored, path));
+  if (!entries) return;
+  for (const [entryName, value] of Object.entries(entries).sort(
+    ([left], [right]) => left.localeCompare(right)
+  )) {
+    const record = objectRecord(value);
+    if (!record) continue;
+    for (const key of Object.keys(record).sort()) {
+      if (!allowed.has(key)) {
+        diagnostics.push(unconsumedKeyDiagnostic([...path, entryName, key]));
+      }
+    }
+  }
+}
+function stableConfigDiagnostics(diagnostics) {
+  const unique = /* @__PURE__ */ new Map();
+  for (const diagnostic of diagnostics) {
+    unique.set(`${diagnostic.code}\0${diagnostic.path}`, diagnostic);
+  }
+  return [...unique.values()].sort(
+    (left, right) => left.path.localeCompare(right.path) || left.code.localeCompare(right.code) || left.message.localeCompare(right.message)
+  );
+}
+function detectUnconsumedConfigKeys(authoredConfig, parsedConfig) {
+  const diagnostics = [];
+  collectStrippedKeys(authoredConfig, parsedConfig, [], diagnostics);
+  for (const boundary of PASSTHROUGH_KEYS) {
+    collectPassthroughKeys(
+      authoredConfig,
+      boundary.path,
+      new Set(boundary.keys),
+      diagnostics
+    );
+  }
+  collectRuleConfigKeys(authoredConfig, ["govern", "rules"], diagnostics);
+  collectPassthroughRecordValues(
+    authoredConfig,
+    ["govern", "agents"],
+    /* @__PURE__ */ new Set(["rules"]),
+    diagnostics
+  );
+  collectPassthroughKeys(authoredConfig, ["govern", "audit"], /* @__PURE__ */ new Set(), diagnostics);
+  collectPassthroughRecordValues(authoredConfig, ["govern", "runners"], /* @__PURE__ */ new Set(), diagnostics);
+  return stableConfigDiagnostics(diagnostics);
+}
+function effectiveScaleBindings(policy) {
+  const bindings = [];
+  for (const style of policy?.styles ?? []) {
+    if (style.kind === "style.rawSpacing.mustMatchScale") {
+      bindings.push({
+        label: "Spacing properties",
+        mechanism: "style.rawSpacing.mustMatchScale",
+        scale: style.scale
+      });
+    } else if (style.kind === "style.fontSize.mustMatchScale") {
+      bindings.push({
+        label: "Font-size properties",
+        mechanism: "style.fontSize.mustMatchScale",
+        scale: style.scale
+      });
+    }
+  }
+  return bindings;
+}
+function detectOrphanGovernanceScales(declaredPolicy, effectivePolicy) {
+  const bindings = effectiveScaleBindings(effectivePolicy);
+  const referenced = new Set(bindings.map((binding) => binding.scale));
+  const diagnostics = [];
+  for (const scale of Object.keys(declaredPolicy?.scales ?? {}).sort()) {
+    if (referenced.has(scale)) continue;
+    const path = `govern.scales.${scale}`;
+    const preferred = (scale.toLowerCase().includes("spac") ? bindings.find((binding) => binding.mechanism === "style.rawSpacing.mustMatchScale") : void 0) ?? (scale.toLowerCase().includes("font") ? bindings.find((binding) => binding.mechanism === "style.fontSize.mustMatchScale") : void 0) ?? bindings[0];
+    const remediation = preferred ? `${preferred.label} are bound to the scale named "${preferred.scale}" \u2014 rename the key to "${preferred.scale}" or bind it via ${preferred.mechanism}.` : `Bind it via style.rawSpacing.mustMatchScale or style.fontSize.mustMatchScale, or remove it.`;
+    diagnostics.push({
+      code: "FUI9005",
+      kind: "orphan-scale",
+      severity: "warn",
+      path,
+      message: `${path} is not referenced by any property policy. ${remediation}`
+    });
+  }
+  return stableConfigDiagnostics(diagnostics);
+}
 function summarize(status, flags) {
   if (status === "inert") {
     return "Governance inert \u2014 no enforceable rule family is armed";
@@ -8421,6 +8839,7 @@ function summarize(status, flags) {
 }
 function evaluateGovernanceIntegrity(input) {
   const configs = effectiveRuleConfigs(input.policy);
+  const configDiagnostics = stableConfigDiagnostics(input.configDiagnostics ?? []);
   const policyArmed = input.policy !== void 0 && input.policySource !== "none";
   const policyFamily = {
     id: "policy",
@@ -8431,19 +8850,23 @@ function evaluateGovernanceIntegrity(input) {
     policyFamily.reason = "no governance policy resolved";
   }
   const componentsConfig = configs.get("components/prefer-library");
-  const componentsArmed = componentsConfig?.enabled === true && hasEffectiveComponentVocabulary(componentsConfig.options);
+  const confirmedBridges = input.policy?.canonicalBridges ?? [];
+  const componentsArmed = confirmedBridges.length > 0 || componentsConfig?.enabled === true && hasEffectiveComponentVocabulary(componentsConfig.options);
   const componentsFamily = {
     id: "components",
     armed: componentsArmed,
-    rules: ["components/prefer-library"]
+    rules: [
+      ...confirmedBridges.length > 0 ? ["imports/preferred-path"] : [],
+      ...componentsConfig?.enabled === true ? ["components/prefer-library"] : []
+    ]
   };
   if (!componentsArmed) {
     if (componentsConfig?.enabled === true) {
       componentsFamily.reason = "components/prefer-library enabled but no effective canonical source";
-      componentsFamily.remediation = "add govern.canonicalSources (a directory source, or npm/registry with a non-empty include) or designSystem.path/packageName";
+      componentsFamily.remediation = "add govern.canonicalBridges for local wrappers, govern.canonicalSources, 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";
+      componentsFamily.remediation = "add govern.canonicalBridges for local wrappers, govern.canonicalSources, or designSystem.path/packageName";
     }
   }
   const cssVarsActive = input.cssVarsActive ?? policyDeclaresCssVars(input.policy);
@@ -8517,6 +8940,17 @@ function evaluateGovernanceIntegrity(input) {
     families.map((family) => family.remediation).filter((remediation) => remediation !== void 0)
   );
   const summary = summarize(status, { componentsArmed, tokensArmed, blockingArmed });
+  const configuredRuleCount = [...configs.keys()].filter(
+    (ruleId) => CONSUMED_RULE_IDS.has(ruleId)
+  ).length;
+  const activeRuleCount = [...configs.entries()].filter(
+    ([ruleId, config]) => CONSUMED_RULE_IDS.has(ruleId) && config.enabled
+  ).length;
+  const roster = {
+    configured: configuredRuleCount + configDiagnostics.length,
+    active: activeRuleCount,
+    inert: configDiagnostics.length
+  };
   return {
     status,
     declared: input.declared,
@@ -8525,10 +8959,80 @@ function evaluateGovernanceIntegrity(input) {
     families,
     armed,
     summary,
-    remediations
+    remediations,
+    configDiagnostics,
+    roster
   };
 }
 
+// src/canonical-bridge.ts
+function canonicalBridgeContractMappings(bridges) {
+  return (bridges ?? []).map((bridge) => ({
+    component: `${bridge.underlying.packageName}#${bridge.underlying.exportName}`,
+    canonical: bridge.local.componentKey,
+    status: "confirmed",
+    importPath: bridge.local.moduleSpecifier,
+    bridge: {
+      underlyingPackageName: bridge.underlying.packageName,
+      underlyingExportName: bridge.underlying.exportName,
+      localComponentKey: bridge.local.componentKey,
+      localExportName: bridge.local.exportName,
+      implementationFiles: [...bridge.local.implementationFiles],
+      decisionSource: bridge.decision.source
+    }
+  }));
+}
+
+// src/effective-governance-inputs.ts
+var EFFECTIVE_GOVERNANCE_INPUTS_SCHEMA = "effective-governance-inputs:v1";
+function compileEffectiveGovernanceInputs(options) {
+  const projection = {
+    schema: EFFECTIVE_GOVERNANCE_INPUTS_SCHEMA,
+    policySource: options.policySource,
+    config: {
+      path: options.configPath ? normalizePath2(options.configPath) : null,
+      digest: options.configDigest
+    },
+    components: {
+      canonicalSources: sortRecords(options.policy?.canonicalSources ?? []),
+      canonicalBridges: sortRecords(options.policy?.canonicalBridges ?? []),
+      definitionFiles: normalizePaths(options.componentDefinitionFiles)
+    },
+    tokens: {
+      declared: normalizePaths(options.tokens.declared),
+      loadedDefinitions: options.tokens.loadedDefinitions,
+      diagnostics: [...options.tokens.diagnostics].sort(),
+      ...options.tokens.catalog ? {
+        catalog: {
+          ...options.tokens.catalog,
+          configuredSources: normalizePaths(options.tokens.catalog.configuredSources),
+          parsedSources: normalizePaths(options.tokens.catalog.parsedSources),
+          definitions: sortRecords(options.tokens.catalog.definitions),
+          diagnostics: sortRecords(options.tokens.catalog.diagnostics),
+          references: sortRecords(options.tokens.catalog.references),
+          ...options.tokens.catalog.sourceStates ? { sourceStates: sortRecords(options.tokens.catalog.sourceStates) } : {}
+        }
+      } : {}
+    },
+    eligibility: {
+      include: normalizePaths(options.eligibility.include),
+      exclude: normalizePaths(options.eligibility.exclude)
+    }
+  };
+  return { ...projection, inputsHash: contractHash(projection) };
+}
+function normalizePaths(values) {
+  return [...new Set(values.map(normalizePath2))].sort();
+}
+function normalizePath2(value) {
+  return value.replace(/\\/gu, "/").replace(/^\.\//u, "");
+}
+function sortRecords(values) {
+  return [...values].sort(
+    (left, right) => canonicalPreimage(left).localeCompare(canonicalPreimage(right))
+  );
+}
+
 // src/contract/preimage.ts
 var CONTRACT_DOMAINS = ["components", "tokens", "canonicalMap", "policy"];
 var CONTRACT_PREIMAGE_SCHEMA = "fcid-preimage:v1";
@@ -8584,6 +9088,15 @@ function projectCanonicalMap(mappings) {
       component: mapping.component,
       canonical: mapping.canonical,
       importPath: mapping.importPath ? projectV1OwnedImportIdentity(mapping.importPath) : void 0,
+      bridge: mapping.bridge ? {
+        underlyingPackageName: projectV1OwnedImportIdentity(
+          mapping.bridge.underlyingPackageName
+        ),
+        underlyingExportName: mapping.bridge.underlyingExportName,
+        localComponentKey: projectV1OwnedComponentId(mapping.bridge.localComponentKey),
+        localExportName: mapping.bridge.localExportName,
+        implementationFiles: [...mapping.bridge.implementationFiles].sort()
+      } : void 0,
       resolves: mapping.resolves ? sortCanonical(mapping.resolves) : void 0,
       propMapping: mapping.propMapping ? sortCanonical(
         mapping.propMapping.map((entry) => ({
@@ -9016,6 +9529,7 @@ export {
   DEFAULTS,
   DEFAULT_ENHANCED_STYLE_PROPERTIES,
   DEFAULT_STYLE_PROPERTIES,
+  EFFECTIVE_GOVERNANCE_INPUTS_SCHEMA,
   EVIDENCE_ORDER,
   EXPLAIN_URL_BASE,
   FRAGMENTS_INTERNAL_RULE_IDS,
@@ -9070,6 +9584,9 @@ export {
   byRuleId,
   calculateDeltaE,
   canBlock,
+  canonicalBridgeContractMappings,
+  canonicalBridgeV1Schema,
+  canonicalDirectionConflictsTarget,
   canonicalJson,
   canonicalPreimage,
   canonicalizeOwnedComponentId,
@@ -9092,6 +9609,7 @@ export {
   compareStylesWithTokens,
   compileBlock,
   compileComponentFacts,
+  compileEffectiveGovernanceInputs,
   compileFragment,
   compileGlobalGovernanceFacts,
   compileRecipe,
@@ -9104,6 +9622,7 @@ export {
   compositionMetadataSchema,
   compositionPatternSchema,
   computeRegistryHash,
+  configDeclarationForDiagnostics,
   containsTailwindV4Theme,
   contractComponentsFromFragments,
   contractHash,
@@ -9114,7 +9633,9 @@ export {
   defineConfig,
   defineFragment,
   defineRecipe,
+  detectOrphanGovernanceScales,
   detectSubComponentPaths,
+  detectUnconsumedConfigKeys,
   diffContractDomains,
   discoverComponents,
   dtcgTokenFileSchema,
@@ -9287,6 +9808,7 @@ export {
   parseTokenFile,
   parseTokens,
   portableRepoPathError,
+  projectCanonicalDirectionConflicts,
   projectContractPreimage,
   projectV1OwnedComponentId,
   projectV1OwnedImportIdentity,