@usefragments/core 1.5.0 → 1.5.1

package/dist/react-types.d.ts

@@ -1,5 +1,5 @@
 import { ComponentType, ReactNode, JSX } from 'react';
-export { F as FragmentDefinition, a as FragmentDefinitionV2 } from './governance-BLsyk56o.js';
+export { F as FragmentDefinition, a as FragmentDefinitionV2 } from './governance-B88uR3Zq.js';
 import 'zod';
 import './topology/index.js';
 import './types-xJ2xyp_G.js';

package/dist/schemas/index.d.ts

@@ -1,3 +1,3 @@
 import 'zod';
 export { LegacySeverityLevel, Severity, SeverityLevel, legacySeverityLevelSchema, severityLevelSchema, severitySchema } from '../severity.js';
-export { b as AGENT_FORMAT_SCHEMA_VERSION, c as AgentErrorEnvelope, A as AgentFormat, d as AgentOutput, Q as FactEvidence, R as FactLocation, F as Finding, a as FindingFix, f as FindingReplaceClassTokenFix, g as FindingReplaceComponentFix, h as FindingReplaceImportFix, i as FindingReplacePropValueFix, j as FindingReplaceStyleValueFix, k as Fix, G as GovernanceVerdict, l as GovernanceVerdictMetadata, S as SuppressionDirective, V as ValidatorResult, n as Violation, o as agentErrorEnvelopeSchema, T as agentFindingSchema, p as agentFormatSchema, q as agentIntegritySchema, r as agentOutputSchema, U as agentPlanSchema, t as factEvidenceSchema, u as factLocationSchema, v as findingFixSchema, w as findingReplaceClassTokenFixSchema, x as findingReplaceComponentFixSchema, y as findingReplaceImportFixSchema, z as findingReplacePropValueFixSchema, B as findingReplaceStyleValueFixSchema, C as findingSchema, D as fixSchema, H as governanceVerdictMetadataSchema, J as governanceVerdictSchema, K as normalizeFinding, L as normalizeSeverity, M as normalizeViolation, N as suppressionDirectiveSchema, O as validatorResultSchema, P as violationSchema } from '../index-h_yWj15D.js';
+export { b as AGENT_FORMAT_SCHEMA_VERSION, c as AgentErrorEnvelope, A as AgentFormat, d as AgentOutput, Q as FactEvidence, R as FactLocation, F as Finding, a as FindingFix, f as FindingReplaceClassTokenFix, g as FindingReplaceComponentFix, h as FindingReplaceImportFix, i as FindingReplacePropValueFix, j as FindingReplaceStyleValueFix, k as Fix, G as GovernanceVerdict, l as GovernanceVerdictMetadata, S as SuppressionDirective, V as ValidatorResult, n as Violation, o as agentErrorEnvelopeSchema, T as agentFindingSchema, p as agentFormatSchema, q as agentIntegritySchema, r as agentOutputSchema, U as agentPlanSchema, t as factEvidenceSchema, u as factLocationSchema, v as findingFixSchema, w as findingReplaceClassTokenFixSchema, x as findingReplaceComponentFixSchema, y as findingReplaceImportFixSchema, z as findingReplacePropValueFixSchema, B as findingReplaceStyleValueFixSchema, C as findingSchema, D as fixSchema, H as governanceVerdictMetadataSchema, J as governanceVerdictSchema, K as normalizeFinding, L as normalizeSeverity, M as normalizeViolation, N as suppressionDirectiveSchema, O as validatorResultSchema, P as violationSchema } from '../index-DbkPE46t.js';

package/dist/schemas/index.js

@@ -24,7 +24,7 @@ import {
   suppressionDirectiveSchema,
   validatorResultSchema,
   violationSchema
-} from "../chunk-57QDBEHQ.js";
+} from "../chunk-ZHS52OT4.js";
 import {
   legacySeverityLevelSchema,
   severityLevelSchema,

package/dist/test-utils.d.ts

@@ -1,4 +1,4 @@
-import { C as CompiledBlock, b as CompiledFragment } from './governance-BLsyk56o.js';
+import { C as CompiledBlock, b as CompiledFragment } from './governance-B88uR3Zq.js';
 import 'zod';
 import 'react';
 import './topology/index.js';

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@usefragments/core",
-  "version": "1.5.0",
+  "version": "1.5.1",
   "license": "MIT",
   "description": "Core types, schemas, and runtime API for Fragments component definitions",
   "author": "Conan McNicholl",

package/src/agent-format.test.ts

@@ -232,6 +232,7 @@ describe("buildAgentFormat", () => {
         scope: { method: "full", gitOk: true },
         engineVersion: `sha256:${"b".repeat(64)}`,
         scopeHash: "c".repeat(64),
+        inputsHash: "e".repeat(64),
         inputFilesHash: "d".repeat(64),
       },
       verdict: { exitCode: 0, reasons: [], gatingFindingCount: 0 },

package/src/canonical-bridge.ts

@@ -0,0 +1,46 @@
+import type { ContractCanonicalMappingInput } from "./contract/preimage.js";
+import type { CanonicalBridgeV1 } from "./governance.js";
+import { ownedImportMatchesRoot } from "./package-identity-match.js";
+
+export function canonicalBridgeUnderlyingKey(input: {
+  packageName: string;
+  exportName: string;
+}): string {
+  return `${input.packageName}\u0000${input.exportName}`;
+}
+
+export function canonicalBridgeContractMappings(
+  bridges: readonly CanonicalBridgeV1[] | undefined
+): ContractCanonicalMappingInput[] {
+  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,
+    },
+  }));
+}
+
+export function canonicalBridgeMatchesUnderlyingImport(
+  bridge: CanonicalBridgeV1,
+  source: string,
+  imported: string
+): boolean {
+  if (!ownedImportMatchesRoot(source, bridge.underlying.packageName)) return false;
+  if (source === bridge.underlying.packageName) {
+    return imported === bridge.underlying.exportName;
+  }
+  const subpath = source.slice(bridge.underlying.packageName.length + 1);
+  const leaf = subpath.split("/").at(-1);
+  return (
+    leaf === bridge.underlying.exportName &&
+    (imported === "default" || imported === bridge.underlying.exportName)
+  );
+}

package/src/canonical-direction.ts

@@ -0,0 +1,118 @@
+import type { CanonicalSource } from "./governance.js";
+import type { FactIndex } from "./facts/index.js";
+import { ownedImportMatchesRoot } from "./package-identity-match.js";
+
+export interface CanonicalDirectionConflict {
+  packageName: string;
+  exportName: string;
+  wrapperComponentKey: string;
+  wrapperFile: string;
+  wrapperExportName: string;
+  state: "unresolved" | "sanctioned";
+}
+
+/**
+ * Project exact, source-backed conflicts between an exported local wrapper and
+ * an npm canonical export. Name similarity, prop overlap, and mixed render
+ * trees are deliberately insufficient: this projection can deactivate policy.
+ */
+export function projectCanonicalDirectionConflicts(
+  ix: FactIndex,
+  canonicalSources: readonly CanonicalSource[]
+): CanonicalDirectionConflict[] {
+  const npmSources = canonicalSources.filter(
+    (source): source is Extract<CanonicalSource, { kind: "npm" }> => source.kind === "npm"
+  );
+  if (npmSources.length === 0) return [];
+
+  const identityByComponent = new Map(
+    ix.byKind("component_identity").map((identity) => [identity.componentKey, identity])
+  );
+  const conflicts: CanonicalDirectionConflict[] = [];
+
+  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)
+  );
+}
+
+export function canonicalDirectionConflictsTarget(
+  conflicts: readonly CanonicalDirectionConflict[],
+  importPath: string | undefined,
+  exportName: string
+): boolean {
+  if (!importPath) return false;
+  return conflicts.some(
+    (conflict) =>
+      ownedImportMatchesRoot(importPath, conflict.packageName) && conflict.exportName === exportName
+  );
+}
+
+function npmTarget(
+  canonicalTarget: string,
+  sources: readonly Extract<CanonicalSource, { kind: "npm" }>[]
+): { packageName: string; exportName: string } | null {
+  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: string, packageName: string): string {
+  return importPath === packageName ? "" : importPath.slice(packageName.length + 1);
+}
+
+function decisionTargetsExport(target: string | undefined, exportName: string): boolean {
+  if (!target) return true;
+  return target === exportName || target.split("#").at(-1)?.split(".").at(-1) === exportName;
+}

package/src/codes/codes.ts

@@ -264,6 +264,15 @@ export const CODES = [
     lifecycle: "experimental",
     evidenceRequired: true,
   }),
+  ruleCode({
+    code: "FUI2017",
+    ruleId: "tokens/upstream-drift",
+    category: "tokens",
+    defaultSeverity: "moderate",
+    title: "Local token differs from its declared upstream source",
+    lifecycle: "experimental",
+    evidenceRequired: true,
+  }),
   ruleCode({
     code: "FUI3001",
     ruleId: "a11y/required-accessible-name",

package/src/contract/preimage.test.ts

@@ -162,6 +162,46 @@ describe("§3 proposed mappings are not identity", () => {
   });
 });
 
+describe("confirmed canonical bridge identity", () => {
+  const bridgeMapping = {
+    component: "@mui/material#Button",
+    canonical: "src/components/Button.tsx#Button",
+    status: "confirmed" as const,
+    importPath: "@/components",
+    bridge: {
+      underlyingPackageName: "@mui/material",
+      underlyingExportName: "Button",
+      localComponentKey: "src/components/Button.tsx#Button",
+      localExportName: "Button",
+      implementationFiles: ["src/components/Button.tsx"],
+      decisionSource: "authored" as const,
+    },
+  };
+
+  it("moves only canonicalMap when enforcement changes, not when provenance changes", () => {
+    const base = projectContractPreimage({ canonicalMappings: [bridgeMapping] });
+    const changedEnforcement = projectContractPreimage({
+      canonicalMappings: [
+        {
+          ...bridgeMapping,
+          bridge: { ...bridgeMapping.bridge, implementationFiles: ["src/ui/Button.tsx"] },
+        },
+      ],
+    });
+    const changedProvenance = projectContractPreimage({
+      canonicalMappings: [
+        {
+          ...bridgeMapping,
+          bridge: { ...bridgeMapping.bridge, decisionSource: "migration" as const },
+        },
+      ],
+    });
+
+    expect(diffContractDomains(base, changedEnforcement)).toEqual(["canonicalMap"]);
+    expect(changedProvenance).toEqual(base);
+  });
+});
+
 describe("§4 domain diff names what moved", () => {
   it("confirming a mapping + adding a composition rule changes canonicalMap and policy", () => {
     const preimageBase = projectContractPreimage(catalogFixtureA);

package/src/contract/preimage.ts

@@ -87,6 +87,15 @@ export interface ContractCanonicalMappingInput {
   status: CanonicalMappingStatus;
   /** Local/offline canonical import target, when the mapping is config-authored. */
   importPath?: string;
+  /** Confirmed package-to-local relation metadata. Absent for legacy mappings. */
+  bridge?: {
+    underlyingPackageName: string;
+    underlyingExportName: string;
+    localComponentKey: string;
+    localExportName: string;
+    implementationFiles: readonly string[];
+    decisionSource: "authored" | "migration";
+  };
   /** Explicit raw element or semantic resolutions covered by a local declaration. */
   resolves?: readonly {
     tag: string;
@@ -253,6 +262,17 @@ function projectCanonicalMap(
         importPath: mapping.importPath
           ? projectV1OwnedImportIdentity(mapping.importPath)
           : undefined,
+        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(),
+            }
+          : undefined,
         resolves: mapping.resolves ? sortCanonical(mapping.resolves) : undefined,
         propMapping: mapping.propMapping
           ? sortCanonical(

package/src/effective-governance-inputs.test.ts

@@ -0,0 +1,52 @@
+import { describe, expect, it } from "vitest";
+
+import { compileEffectiveGovernanceInputs } from "./effective-governance-inputs.js";
+
+function fixture() {
+  return compileEffectiveGovernanceInputs({
+    policySource: "config",
+    configPath: "./fragments.config.ts",
+    configDigest: "a".repeat(64),
+    policy: {
+      canonicalBridges: [
+        {
+          underlying: { packageName: "@mui/material", exportName: "Button" },
+          local: {
+            componentKey: "src/components/Button.tsx#Button",
+            moduleSpecifier: "@/components/Button",
+            exportName: "Button",
+            implementationFiles: ["src/components/Button.tsx"],
+          },
+          decision: { state: "confirmed", source: "authored" },
+        },
+      ],
+    },
+    componentDefinitionFiles: ["src/components/Button.tsx"],
+    tokens: { declared: [], loadedDefinitions: 0, diagnostics: [] },
+    eligibility: { include: ["src/**/*.tsx"], exclude: ["src/**/*.stories.tsx"] },
+  });
+}
+
+describe("compileEffectiveGovernanceInputs", () => {
+  it("normalizes operational inputs into a separate stable identity", () => {
+    const first = fixture();
+    const second = fixture();
+    expect(first).toEqual(second);
+    expect(first.inputsHash).toMatch(/^[a-f0-9]{64}$/u);
+    expect(first.config.path).toBe("fragments.config.ts");
+  });
+
+  it("moves inputsHash for config/source state without changing contract identity here", () => {
+    const first = fixture();
+    const next = compileEffectiveGovernanceInputs({
+      policySource: first.policySource,
+      configPath: first.config.path,
+      configDigest: "b".repeat(64),
+      policy: { canonicalBridges: first.components.canonicalBridges },
+      componentDefinitionFiles: first.components.definitionFiles,
+      tokens: { declared: [], loadedDefinitions: 0, diagnostics: [] },
+      eligibility: first.eligibility,
+    });
+    expect(next.inputsHash).not.toBe(first.inputsHash);
+  });
+});

package/src/effective-governance-inputs.ts

@@ -0,0 +1,106 @@
+import { canonicalPreimage, contractHash } from "./contract/hash.js";
+import type { GovernanceConfig } from "./governance.js";
+import type { TokenCatalog } from "./token-types.js";
+
+export const EFFECTIVE_GOVERNANCE_INPUTS_SCHEMA = "effective-governance-inputs:v1" as const;
+
+export interface EffectiveGovernanceInputsSourceState {
+  declared: readonly string[];
+  loadedDefinitions: number;
+  diagnostics: readonly string[];
+  catalog?: TokenCatalog;
+}
+
+export interface CompileEffectiveGovernanceInputsOptions {
+  policySource: "config" | "preset" | "fallback" | "none";
+  configPath: string | null;
+  configDigest: string | null;
+  policy: GovernanceConfig | undefined;
+  componentDefinitionFiles: readonly string[];
+  tokens: EffectiveGovernanceInputsSourceState;
+  eligibility: {
+    include: readonly string[];
+    exclude: readonly string[];
+  };
+}
+
+export interface EffectiveGovernanceInputs {
+  schema: typeof EFFECTIVE_GOVERNANCE_INPUTS_SCHEMA;
+  policySource: CompileEffectiveGovernanceInputsOptions["policySource"];
+  config: { path: string | null; digest: string | null };
+  components: {
+    canonicalSources: NonNullable<GovernanceConfig["canonicalSources"]>;
+    canonicalBridges: NonNullable<GovernanceConfig["canonicalBridges"]>;
+    definitionFiles: string[];
+  };
+  tokens: {
+    declared: string[];
+    loadedDefinitions: number;
+    diagnostics: string[];
+    catalog?: TokenCatalog;
+  };
+  eligibility: { include: string[]; exclude: string[] };
+  inputsHash: string;
+}
+
+/**
+ * Compile one deterministic, post-authority account of the operational inputs
+ * available to governance consumers. This is deliberately distinct from FCID
+ * (enforced contract identity) and scopeHash (the files selected for one Run).
+ */
+export function compileEffectiveGovernanceInputs(
+  options: CompileEffectiveGovernanceInputsOptions
+): EffectiveGovernanceInputs {
+  const projection = {
+    schema: EFFECTIVE_GOVERNANCE_INPUTS_SCHEMA,
+    policySource: options.policySource,
+    config: {
+      path: options.configPath ? normalizePath(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: readonly string[]): string[] {
+  return [...new Set(values.map(normalizePath))].sort();
+}
+
+function normalizePath(value: string): string {
+  return value.replace(/\\/gu, "/").replace(/^\.\//u, "");
+}
+
+function sortRecords<T>(values: readonly T[]): T[] {
+  return [...values].sort((left, right) =>
+    canonicalPreimage(left).localeCompare(canonicalPreimage(right))
+  );
+}

package/src/facts/builders.ts

@@ -104,6 +104,7 @@ export function makeComponentCapabilityFact(input: {
 export function makeComponentDefinitionFact(input: {
   file: string;
   exportName: string;
+  exported?: boolean;
   componentKey: string;
   renderRoot: ComponentDefinitionFact["renderRoot"];
   propSurface: string[];
@@ -115,6 +116,7 @@ export function makeComponentDefinitionFact(input: {
     componentId: asComponentId(input.componentKey),
     file: input.file,
     exportName: input.exportName,
+    exported: input.exported ?? false,
     componentKey: input.componentKey,
     renderRoot: input.renderRoot,
     propSurface: [...input.propSurface],
@@ -467,12 +469,14 @@ export function makeJsxImportPathPreferredFact(input: {
   imported?: string;
   because?: string;
   severity: GovernanceSeverity;
+  bridge?: JsxImportPathPreferredFact["bridge"];
 }): JsxImportPathPreferredFact {
   return {
     id: factId("jsx_import_path_preferred", {
       from: input.from,
       to: input.to,
       imported: input.imported,
+      bridge: input.bridge,
     }),
     kind: "jsx_import_path_preferred",
     from: input.from,
@@ -480,6 +484,14 @@ export function makeJsxImportPathPreferredFact(input: {
     imported: input.imported,
     because: input.because,
     severity: input.severity,
+    ...(input.bridge
+      ? {
+          bridge: {
+            ...input.bridge,
+            implementationFiles: [...input.bridge.implementationFiles],
+          },
+        }
+      : {}),
   };
 }
 
@@ -509,9 +521,17 @@ export function makeTokenDefinitionFact(input: {
   category?: TokenDefinitionFact["category"];
   referenceFormat?: TokenDefinitionFact["referenceFormat"];
   sourceNames?: TokenDefinitionFact["sourceNames"];
+  role?: TokenDefinitionFact["role"];
+  authority?: TokenDefinitionFact["authority"];
+  sourceIdentity?: TokenDefinitionFact["sourceIdentity"];
+  upstreamName?: TokenDefinitionFact["upstreamName"];
 }): TokenDefinitionFact {
+  const authorityIdentity =
+    input.role || input.sourceIdentity
+      ? { role: input.role ?? "local", sourceIdentity: input.sourceIdentity ?? "" }
+      : {};
   return {
-    id: factId("token_definition", { name: input.name }),
+    id: factId("token_definition", { name: input.name, ...authorityIdentity }),
     kind: "token_definition",
     name: input.name,
     value: input.value,
@@ -519,6 +539,10 @@ export function makeTokenDefinitionFact(input: {
     category: input.category,
     referenceFormat: input.referenceFormat,
     ...(input.sourceNames?.length ? { sourceNames: [...input.sourceNames] } : {}),
+    ...(input.role ? { role: input.role } : {}),
+    ...(input.authority ? { authority: input.authority } : {}),
+    ...(input.sourceIdentity ? { sourceIdentity: input.sourceIdentity } : {}),
+    ...(input.upstreamName ? { upstreamName: input.upstreamName } : {}),
   };
 }
 

package/src/facts/compile.ts

@@ -153,6 +153,25 @@ export function compileGlobalGovernanceFacts(govern: GovernanceConfig | undefine
     }
   }
 
+  for (const bridge of govern.canonicalBridges ?? []) {
+    out.push(
+      makeJsxImportPathPreferredFact({
+        from: bridge.underlying.packageName,
+        to: bridge.local.moduleSpecifier,
+        imported: bridge.underlying.exportName,
+        because: `Use the confirmed local ${bridge.local.exportName} wrapper`,
+        severity: ruleSeverity(govern.rules?.["imports/preferred-path"], govern.severity ?? "warn"),
+        bridge: {
+          componentKey: bridge.local.componentKey,
+          localExportName: bridge.local.exportName,
+          underlyingExportName: bridge.underlying.exportName,
+          implementationFiles: [...bridge.local.implementationFiles],
+          decisionSource: bridge.decision.source,
+        },
+      })
+    );
+  }
+
   const tailwindPalette = govern.tailwind?.palette;
   const forbiddenPaletteSeverity = ruleSeverity(
     govern.rules?.["tailwind/forbidden-palette"],
@@ -230,8 +249,7 @@ function compileRuleConfigFacts(govern: GovernanceConfig): PolicyFact[] {
       severity: existing?.severity ?? govern.severity ?? "warn",
       options: {
         ...existing?.options,
-        canonicalSources:
-          existing?.options?.canonicalSources ?? govern.canonicalSources,
+        canonicalSources: existing?.options?.canonicalSources ?? govern.canonicalSources,
       },
     });
   }

package/src/facts/fact-index.ts

@@ -360,6 +360,10 @@ export class FactIndex {
   // ---------------------------------------------------------------------
 
   private indexTokenSymbols(fact: TokenDefinitionFact): void {
+    // Upstream definitions are comparison evidence, not local replacement
+    // candidates. Keeping them out of the reverse symbol index also prevents a
+    // known-drift upstream value from making the local token look safe.
+    if (fact.role === "upstream") return;
     const legacyScssAlias =
       fact.referenceFormat === "scss-var" && fact.name.startsWith("--")
         ? `$${fact.name.slice(2)}`

package/src/facts/types.ts

@@ -184,6 +184,14 @@ export interface JsxImportPathPreferredFact extends BaseFact {
   imported?: string;
   because?: string;
   severity: GovernanceSeverity;
+  /** Present when the policy was compiled from a confirmed local-canonical bridge. */
+  bridge?: {
+    componentKey: string;
+    localExportName: string;
+    underlyingExportName: string;
+    implementationFiles: string[];
+    decisionSource: "authored" | "migration";
+  };
 }
 
 export interface JsxComponentPreferredFact extends BaseFact {
@@ -197,7 +205,9 @@ export interface JsxComponentPreferredFact extends BaseFact {
 /**
  * A design token from the system. Used by fixes (e.g., raw color → token
  * substitution) and rules that need to know the token vocabulary. Identity is
- * the token `name`; two scans of the same token registry produce the same ID.
+ * the token `name` for legacy/local facts. Authority-aware facts also include
+ * role and source identity so same-name local/upstream definitions cannot
+ * silently collapse in the fact index.
  */
 export interface TokenDefinitionFact extends BaseFact {
   kind: "token_definition";
@@ -212,14 +222,21 @@ export interface TokenDefinitionFact extends BaseFact {
    * How the token is referenced from authored styles, inferred from its source.
    * Governs whether a "use the token" fix can be *applied* automatically: a
    * `css-var`/`scss-var` reference resolves verbatim, but a `scss-map` member
-   * (`$colors-primary` minted from a Sass map) or a `dtcg` JSON token (no CSS
-   * custom property emitted) does not — those are surfaced as suggestions, not
-   * deterministic rewrites, so the fixer never writes non-compiling output.
-   * Absent on legacy/hand-built facts, which are treated as safe.
+   * (`$colors-primary` minted from a Sass map), a `dtcg` JSON token (no CSS
+   * custom property emitted), or a `js-member` path (`colors.primary`) does not
+   * — those are surfaced as suggestions, not deterministic rewrites, so the
+   * fixer never writes invented syntax. Absent on legacy/hand-built facts,
+   * which fail closed because an unknown authored form is not applicability
+   * proof.
    */
-  referenceFormat?: "css-var" | "scss-var" | "scss-map" | "dtcg";
+  referenceFormat?: "css-var" | "scss-var" | "scss-map" | "dtcg" | "js-member";
   /** Original authored spellings retained before parser normalization. */
   sourceNames?: string[];
+  role?: "local" | "upstream";
+  authority?: "authored" | "declared-package";
+  sourceIdentity?: string;
+  /** Authored upstream identity when the local and upstream names differ. */
+  upstreamName?: string;
 }
 
 export interface TailwindPaletteAllowFact extends BaseFact {
@@ -611,6 +628,8 @@ export interface ComponentDefinitionFact extends BaseFact {
   componentId: ComponentId;
   file: string;
   exportName: string;
+  /** Whether this definition is reachable through an authored ESM export. */
+  exported: boolean;
   componentKey: string;
   renderRoot: ComponentDefinitionRenderRoot;
   propSurface: string[];